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Preface 



The IBM Personal Computer offers three upwardly 
compatible versions of the BASIC interpreter: 
Cassette, Disk, and Advanced. This BASIC Reference 
and the companion volume, the BASIC Handbook, are 
references for these three versions of BASIC — and for 
the various releases of BASIC, beginning with 1.0. 

It is important for you to know that these books are 
written only as references for the BASIC programming 
language, not as textbooks that will teach you how to 
program. If you need step-by-step instruction in 
learning to program in BASIC, we suggest that you ask 
for the materials you need at your library, bookstore, or 
computer store. 

This book is an encyclopedia-type manual. It contains, 
in alphabetical order, the syntax and semantics of every 
command, statement, and function in BASIC. 

The BASIC Handbook contains general information 
about using BASIC. There are sections that will help 
you get started using BASIC, and there are some 
sections that contain information on advanced subjects 
for the experienced programmer. 

These two BASIC books are extensively 
cross-referenced and indexed. Each also includes 
appendixes of useful information. In addition, there is a 
Quick Reference that lists all the BASIC commands, 
statements, and functions, categorized by task. 

Note: If you have an IBM PCjr, use the BASIC 
book specifically for the PCjr rather than these 
books. 

The IBM Personal Computer BASIC Compiler is an 
optional software package that is available at your 
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computer store. If you have the BASIC Compiler, 
use the IBM Personal Computer BASIC Compiler 
book in conjunction with this book and the BASIC 
Handbook. 



Related Publications 



The following books contain related information that 
you may find useful: 

• The IBM Personal Computer Guide to Operations. 

• The IBM Personal Computer Disk Operating 
System. 

• The IBM Personal Computer Disk Operating System 
Technical Reference. 

• The IBM Personal Computer Technical Reference. 
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Summary of Changes 



This summary first lists the changes that were made in 
BASIC release 2.0, and then lists the BASIC release 
3.0 changes. 



Changes in BASIC 2.0 and BASIC 2.1 



The changes that were made in BASIC release 2.0 are 
briefly described in the material that follows. 

• Three enhancements were made to the BASIC 
command line: 

- The optional parameter max blocksize was added 
to the /M: switch, allowing you to reserve space 
beyond BASIC'S data segment for assembly 
language subroutines. 

- The ATN, COS, EXP, LOG, SIN, SQR, and 
TAN functions now allow you to calculate in 
double precision by specifying /D in the BASIC 
command line. 

- You can redirect standard input and standard 
output by specifying <stdin or>stdout in the 
BASIC command line. 

• Pressing Ctrl-PrtSc causes text sent to your screen 
to also be sent to your system printer. 

• The filespec syntax was expanded to allow the 
specification of a path for a device or file. All 
commands and statements that accept filespec also 
accept path. The commands that allow paths are 



BLOAD, BSAVE, KILL, LOAD, MERGE, 

NAME, RUN, and SAVE. The statements that 
allow paths are CHAIN and OPEN. 

• The DELETE command syntax was expanded to 
allow line deletions from the specified line to the 
end of the program. 

• The PE option was added to the OPEN "COM... 

statement syntax to allow for parity checking. 

• The PLAY statement has two new options. (For 
use in Advanced BASIC only.) 

- >n raises the octave and plays note n. 

- <n lowers the octave and plays note n. 

• The DRAW statement has two new options. (For 
use in Advanced BASIC only.) 

- TA(«) turns angle n from -360 to 360 degrees. 

- P paint, boundary sets figure color and border 
color. 

• The POINT function allows the form v=POINT(«), 

which returns the value of the current x or y 
graphics coordinate. (For use in Advanced BASIC 
only.) 

• The RANDOMIZE statement allows 
double-precision expressions. 

• The LINE statement has a new option, style, which 
uses hexadecimal values to plot a pattern of points 
on the screen. (For use in Advanced BASIC only.) 

• The PAINT statement has a new feature, tiling, 
which allows you to paint an area with a pattern 
rather than just a solid color. (For use in Advanced 
BASIC only.) 
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. The ON KEY(n), KEY(n), and KEY statements 
now allow trapping of six additional definable keys, 
15-20. (For use in Advanced BASIC only.) 

• The GET and PUT statements were enhanced to 
allow record numbers in the range 1 to 16,777,215 
to accommodate large files with short record 
lengths. 

• EOF(0) returns the end-of-file condition on 
standard input devices used with redirection of I/O. 

• The LOF function returns the actual number of 
bytes allocated to a file. 

• The graphics statements CIRCLE, DRAW, LINE, 
PAINT, POINT, PSET, PRESET, VIEW, and 
WINDOW now use line clipping instead of 
wraparound. 

Three new functions were added: 

• The PLAY(n) function returns the number of notes 
currently in the Music Background (MB) buffer. 
(For use in Advanced BASIC only.) 

• The PMAP function maps an expression to world or 
physical coordinates. (For use in Advanced BASIC 
only.) 

• The TIMER function returns the number of seconds 
that have elapsed since midnight or System Reset. 

Four new statements were added: 

• The ON PLAY statement allows continuous music 
to play while a program is running. (For use in 
Advanced BASIC only.) 

• The ON TIMER statement transfers control to a 
given line number in a BASIC program when a 
defined period of time has elapsed. (For use in 
Advanced BASIC only.) 



Vll 



• The VIEW statement lets you define a viewport (or 
area) within the physical limits of the screen. (For 
use in Advanced BASIC only.) 

• The WINDOW statement lets you redefine the 
coordinates of the screen or viewport. (For use in 
Advanced BASIC only.) 

Three new commands were added: 

• The CHDIR command allows you to change the 
current directory. 

• The MKDIR command creates a directory on the 
specified disk. 

• The RMDIR command removes a directory from 
the specified disk. 



Changes in BASIC 3.0 



The following changes have been made in BASIC 
release 3.0: 

• Device support allows BASIC to communicate with 
user-installed device drivers through the IOCTL 
statement and IOCTL$ function. 

• IOCTL and IOCTL$ are used to get information to 
and from device channels. 

. ENVIRON statement and ENVIRONS function 
allow you to modify parameters in BASIC'S 
environment table. 

• ERDEV and ERDEV$ are device error variables 
that allow you to read INT 24 error codes. 

• SHELL allows you to execute DOS commands and 
run child processes from BASIC. 
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Note: The terms "disk," "diskette," and "fixed 
disk" are used throughout this book. Where 
"diskette" is used, it applies only to diskette drives 
and diskettes. Where "fixed disk" is used, it applies 
only to the IBM nonremovable fixed disk drive. 
Where "disk" is used, it applies to both fixed disks 
and diskettes. 
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BASIC Commands, Statements, and 
Functions 



How to Use This Book 



Descriptions of all the BASIC commands, statements, 
and functions are included in this book. The entries are 
arranged alphabetically. For more background and 
general information on BASIC, refer to the 
accompanying publication, the BASIC Handbook. 

BASIC'S built-in functions and variables can be used in 
any program without further definition. 

The distinction between a command and a statement is 
largely a matter of tradition. Commands, because they 
generally operate on programs, are usually entered in 
direct mode. Statements generally direct program flow 
from within a program, and so are usually entered in 
indirect mode as part of a program line. Actually, most 
BASIC commands and statements can be entered in 
either direct or indirect mode. 

The description of each command, statement, function, 
or variable in this section is formatted as follows: 



Purpose: Tells what the command, statement, function, or 
variable does. 



Versions: Indicates which versions of BASIC allow the 

command, statement, function, or variable. For 
example, if you look under "CHAIN Statement," 
you can see that after Versions: it says: 

Cassette Disk Advanced Compiler 
*** *** (**\ 

The asterisks indicate which versions of BASIC 
support the function. This example shows that you 
can use the CHAIN statement for programs written 
in the Disk BASIC and Advanced BASIC versions of 
BASIC. 

In this example you will notice that the asterisks 
under the word "Compiler" are in parentheses. This 
means that that there are differences between the 
way the statement works under the BASIC 
interpreter and the way it works under the IBM 
Personal Computer BASIC Compiler. The IBM 
Personal Computer BASIC Compiler is an optional 
software package available from your IBM dealer. If 
you have the BASIC Compiler, the IBM Personal 
Computer BASIC Compiler manual explains these 
differences. 

Format: Shows the correct format for the command, 
statement, function, or variable. A complete 
explanation of the syntax format is presented in the 
preface of this book. Remember to keep these rules 
rules in mind: 

• Words in capital letters are keywords and must be 
entered as shown, except that they can be entered 
in any combination of uppercase and lowercase 
letters. BASIC automatically converts letters to 
uppercase (unless they are part of a quoted 
string, remark, or DATA statement). 

• You are to supply any items shown in lowercase 
italic letters. 



Items in square brackets ([ ]) are optional. 



• An ellipsis (...) indicates that an item can be 
repeated as many times as you wish. 

• All punctuation except square brackets (such as 
commas, parentheses, semicolons, hyphens, or 
equal signs) must be included where shown. 

Remarks: Describes in detail how to use the command, 
statement, function, or variable. 

Example: Shows direct mode statements, sample programs, or 
program segments that demonstrate the use of the 
command, statement, function, or variable. 

If a single- or double-precision value is supplied where 
an integer is required, BASIC rounds up the fractional 
portion and uses the resulting integer. 



ABS 

Function 

Purpose: Returns the absolute value of the expression x. 
Versions: Cassette Disk Advanced Compiler 

Format: v = ABS(x) 

Remarks: x can be any numeric expression. 

The absolute value of a number is always positive or 
zero. 

Example: This example shows that the absolute value of -35 is 
positive 35. 

PRINT ABS(7*(-5)) 
35 



ASC 

Function 



Purpose: Returns the ASCII code for the first character of a 
string (x$). 



Versions: Cassette Disk 



Advanced Compiler 



Format: v = ASC(x#) 

Remarks: x$ can be any string expression. 

The result of the ASC function is a numerical value 
that is the ASCII code of the first character of the 
string x$. See Appendix D for a list of ASCII codes. 
If x$ is null, an Illegal function call error is returned. 

The CHR$ function is the inverse of the ASC 
function, and it converts the ASCII code to a 
character. 



Example: This example shows that the ASCII code for a capital 
T is 84. PRINT ASC("TEST") would work just as 
well. 

10 X$ = "TEST" 
20 PRINT ASC(X$) 
RUN 
84 



ATN 
Function 

Purpose: Returns the arctangent of x. 

Versions: Cassette Disk Advanced Compiler 

Format: v = ATN(jc) 

Remarks: x can be a numeric expression of any type. 

The ATN function returns the angle whose tangent is 
x. The result is a value in radians in the range -PI/2 
to PI/2, where PI=3. 141593. 

If you want to convert radians to degrees, multiply 
by 180/PI. 

In BASIC 2.0 and later releases, you can have this 
calculation performed in double-precision by 
specifying /D in the BASIC command line when 
BASIC is initially loaded. See "Options in the 
BASIC Command" in the BASIC Handbook. 



Example: The first example shows the use of the ATN function 
to calculate the arctangent of 3 . 

PRINT ATN(3) 
1. 



ATN 
Function 

The second example finds the angle whose tangent 
is 1. It is .7853983 radians, or 45 degrees. 

10 PI=3 .141593 

20 RADIANS=ATN(1) 
30 DEGREES=RADIANS*180/PI 
40 PRINT RADIANS, DEGREES 
RUN 
.7853983 45 



AUTO 

Command 



Purpose: Automatically generates the next line number each 
time you press Enter. 



Versions: Cassette Disk 



Advanced Compiler 



Format: AUTO [number] [,[increment]] 
Remarks: 

number is the number used to start numbering 

lines. A period (.) can be used in place 
of the line number to indicate the 
current line. 

increment is the value added to each line number 
to get the next line number. 

Numbering begins at number and increases each 
subsequent line number by the value of increment. If 
both values are omitted, the default is 10,10. If 
number is followed by a comma but increment is not 
specified, the last increment specified in an AUTO 
command is assumed. If number is omitted but 
increment is included, then line numbering begins 
with 0. 

AUTO is used for entering programs. It saves having 
to type each line number. 

If AUTO generates a line number that already exists 
in the program, an asterisk (*) is printed after the 
number to warn you that any input will replace the 
existing line. However, if you press Enter 
immediately after the asterisk, the existing line is not 
replaced, and AUTO generates the next line number. 



AUTO 
Command 

AUTO ends when you press Ctrl-Break. The line in 
which Ctrl-Break is typed is not saved. After a 
Ctrl-Break, BASIC returns to command level. 

Note: When in AUTO mode, you can make 
changes only to the current line. If you want to 
change another line on the screen, be sure to exit 
AUTO by first pressing Ctrl-Break. 

Example: This generates line numbers 10, 20, 30, 40, ... 

AUTO 

This generates line numbers 100, 150, 200, ... 

AUTO 100,50 

This generates line numbers 0, 20, 40, 60, ... 

AUTO ,20 

If the increment in the previous AUTO command 
was 50, then this command generates line numbers 
500, 550, 600, 650, ... 

AUTO 500, 



BEEP 

Statement 

Purpose: Causes the speaker to sound. 

Versions: Cassette Disk Advanced Compiler 

Format: BEEP 

Remarks: The BEEP statement causes the speaker to sound at 
800 Hz for 1/4 second. BEEP has the same effect 
as: 

PRINT CHR$(7); 

Example: In this example, the program checks to see if X is out 

of range. If it is, the computer warns you by 
beeping. 

100 IF X < 20 THEN BEEP 
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BLOAD 
Command 



Purpose: Loads a memory image file into memory. 
Versions: Cassette Disk Advanced Compiler 

Format: BLOAD filespec [,offset] 

Remarks: 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. It must 
conform to the rules outlined under 
"Naming Files" in Chapter 3 of the 
BASIC Handbook; otherwise, an error 
occurs. 

offset is an integer expression in the range to 

65535. This is an offset at which the file 
will be loaded into the current segment 
specified by the latest DEF SEG 
statement. 

If offset is omitted, the offset specified at BSAVE is 
assumed. That is, the file is loaded into the same 
location from which it was BSAVED. 

When a BLOAD command is executed, the named 
file is loaded into memory starting at the specified 
location. If the file is to be loaded from the device 
CAS1:, the cassette motor is turned on 
automatically. 

If you are using Cassette Basic and the device name 
is omitted, CAS1: is assumed. CAS1: is the only 
device allowed for BLOAD in Cassette Basic. If you 
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BLOAD 

Command 



are using Disk BASIC or Advanced BASIC and the 
device name is omitted, the DOS default drive is 
used. 

BLOAD is intended for use with a file that has 
previously been saved with BSAVE. BLOAD and 
BSAVE are useful for loading and saving machine 
language programs, but they are not restricted to 
assembly language programs. Any segment can be 
specified as the target or source for these statements 
through the DEF SEG statement. You have a useful 
way of saving and displaying screen images: save 
from or load to the screen buffer. See also Appendix 
B, "Assembly Language Subroutines." 

Warning: 

BASIC does not check the offset of the current 
segment where you are BLOADing. That is, it is 
possible to use BLOAD anywhere in memory. 
Do not BLOAD over BASIC'S stack, BASIC'S 
variable area, or your BASIC program. See the 
memory map in Appendix B. 

Notes when using CAS1:: 

1 . If you enter the BLOAD command in direct 
mode, the file names on the tape are displayed on 
the screen followed by a period (.) and a single 
letter indicating the type of file. This is followed 
by the message Skipped for the files not matching 
the named file, and Found when the named file is 
found. Types of files and the associated letter 
are: 

.B for BASIC programs in internal format 
(created with SAVE command) 

.P for protected BASIC programs in internal 
format (created with SAVE ,P command) 
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BLOAD 

Command 

.A for BASIC programs in ASCII format 
(created with SAVE ,A command) 

.M for memory image files (created with 
BSAVE command) 

.D for data files (created by OPEN followed 
by output statements) 

If the BLOAD command is executed in a BASIC 
program, the file names skipped and found are 
not displayed on the screen. 

2. You can press Ctrl-Break any time during 
BLOAD. This will cause BASIC to exit the 
search and return to direct mode between files or 
after a time-out period. Previous memory 
contents do not change. 

3. If CAS1: is specified as the device and the 
filename is omitted, the next memory image (.M) 
file on the tape is loaded. 
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BLOAD 

Command 

Example: This example loads the screen buffer for the 
Color/Graphics Monitor Adapter, which is at 
segment address HB8000. If you were loading the 
screen buffer for the IBM Monochrome and Parallel 
Printer Adapter, you would have to change line 30 to 
read &HB000. Line 50 loads PICTURE at offset 0, 
segment &HB800. 

10 'load the screen buffer 

20 'point SEG at screen buffer 

30 DEF SEG= &HB800 

40 'load PICTURE into screen buffer 

50 BLOAD "PICTURE", 

The example for the BSAVE command (see the 
next entry) illustrates how PICTURE was saved. 
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BSAVE 

Command 



Purpose: Saves portions of the computer's memory on the 
specified device. 

Versions: Cassette Disk Advanced Compiler 

Format : B S A VE filespec, offset, length 

Remarks: 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. It must 
conform to the rules outlined under 
"Naming Files" in Chapter 3 of the 
BASIC Handbook', otherwise, an error 
occurs. 

offset is an integer expression in the range to 

65535. This is the offset into the 
segment declared by the last DEF SEG. 
Saving starts from this location. See 
"DEF SEG Statement." 

length is an integer expression in the range 1 to 

65535. This is the length of the 
memory image to be saved. 

If offset or length is omitted, a Syntax error occurs 
and the save is canceled. 

In Cassette BASIC, if the device name is omitted, 
CAS1: is assumed. CAS1: is the only device allowed 
for BSAVE in Cassette Basic, In Disk BASIC and 
Advanced BASIC, if the device name is omitted, the 
DOS default disk drive is used. 
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BSAVE 
Command 

If you are saving to CAS1:, the cassette motor is 
turned on and the memory image file is immediately 
written to the tape. 

When you use the DEF SEG statement, you can 
specify any segment as the source segment for the 
BSAVE data. For example, you can save an image 
of the screen by doing a BSAVE of the screen 
buffer. 

Example: As explained under "BLOAD Command", the 
segment address of the 16K screen buffer for 
Color/Graphic Monitor Adapter is HB8000. The 
segment address of the 4K screen buffer for the IBM 
Monochrome Display and Parallel Printer Adapter is 
HB0000. 

The DEF SEG statement must be used to set up the 
segment address to the start of the screen buffer. 
The offset of and length &H4000 specify that the 
entire 16K screen buffer is to be saved. 

10 'Save the color screen buffer 

20 'point segment at screen buffer 

30 DEF SEG= &HB800 

40 'save buffer in file PICTURE 

50 BSAVE "PICTURE", 3 &H4000 
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CALL 

Statement 



Purpose: Calls an assembly language subroutine. 



Versions: Cassette 



Disk 

*** 



Advanced Compiler 



Format: CALL numvar [{variable [,variable]....)] 
Remarks: 

numvar is the name of a numeric variable. The 
value of the variable indicates the offset 
of the subroutine into the current 
segment of memory as defined by the 
last DEF SEG statement. 

variable is the name of a variable to be passed as 
an argument to the assembly language 
subroutine. 

The CALL statement is a way of interfacing 
assembly language programs with BASIC. See 
Appendix B, "Assembly Language Subroutines," for 
specific considerations when using assembly 
language subroutines. 
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CALL 
Statement 

Example: Line 10 sets the segment to BASIC'S segment. Line 
30 declares all scalar values and arrays used in the 
program. Line 40 computes the offset of ARRAY 
into BASIC'S data segment. Line 50 loads the file 
into an integer array, and line 60 calls the routine. 
The variables Q, B$, and C are passed as arguments 
to the routine. 

10 DEF SEG: OPTION BASE 1 

20 DEFINT A-Z 

30 DIM ARRAY(512): P=0: Q=5: B$="TRUE" :B$="TRUE" : C=0 

40 P = VARPTR(ARRAY(D) 

50 BLOAD "ASM.FIL",P 

60 CALL P(Q,B$,C) 
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CDBL 

Function 



Purpose: Converts x to a double-precision number. 



Versions: Cassette Disk 



Advanced Compiler 



Format: v = CDBL(x) 

Remarks: x can be any numeric expression. 

Rules for converting from one numeric precision to 
another are followed as explained in Chapter 3 of the 
BASIC Handbook. See also "CINT" and "CSNG" 
functions for converting numbers to integer and 
single precision. 

Example: The value of CDBL(A) is accurate only to the 
second decimal place after rounding. This is so 
because only two decimal places of accuracy are 
supplied with A. 

10 A = 454.67 
20 PRINT A;CDBL(A) 
RUN 
454.67 454.669982910155 
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CHAIN 

Statement 



Purpose: Transfers control to another program, and passes 
variables to it from the current program. 

Versions: Cassette Disk Advanced Compiler 

*** *** /**") 

Format: CHAIN [MERGE] filespec Wine] [,[ALL] 
[,DELETE range]]] 

Remarks: MERGE brings a section of code into the BASIC 

program as an overlay. That is, a MERGE operation 
is performed with the chaining program. The 
chained-to program must be an ASCII file if it is to 
be merged. Example: 

CHAIN MERGE "A:0VRLAY" ,1000 



filespec 



line 



is a string expression for the file 
specification. In BASIC 2.0 and later 
releases, it can contain a path. It must 
conform to the rules outlined under 
"Naming Files" in Chapter 3 of the 
BASIC Handbook; otherwise, an error 
occurs. The filename is the name of the 
program to which control is transferred. 
Example: 

CHAIN "A:PR0G1" 

is a line number or an expression that 
evaluates to a line number in the 
chained-to program. It specifies the line 
at which the chained-to program is to 
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CHAIN 

Statement 

begin running. If it is omitted, 
execution begins at the first line in the 
chained-to program. 

line is not affected by a RENUM 
command. If PROG1 is renumbered, 
this example CHAIN statement should 
be changed to point to the new line 
number. Example: 



CHAIN "A:PR0G1",1 



ALL specifies that every variable in the current 
program is to be passed to the chained-to program. 
If the ALL option is omitted, you must include a 
COMMON statement in the chaining program to 
pass variables to the chained-to program. See 
"COMMON Statement." Example: 

CHAIN "A:PR0G1", 1000, ALL 

DELETE behaves like the DELETE command. As 
in the DELETE command, the line numbers 
specified as the first and last line of the range must 
exist, or an Illegal function call error occurs. After 
using an overlay, you will usually want to delete it so 
that a new overlay can be brought in. Example: 

CHAIN MERGE "A:0VRLAY2" ,1000 ,DELETE 1000-5000 
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CHAIN 

Statement 



This example deletes lines 1000 through 5000 of 
the chaining program before loading in the overlay 
(chained-to program). The line numbers in range are 
affected by the RENUM command. 

Notes: 

1 . The CHAIN statement leaves files open. 

2. The CHAIN statement with MERGE option 
preserves the current OPTION BASE setting. 

3. Without MERGE, CHAIN does not preserve 
variable types or user-defined functions for use 
by the chained-to program. That is, any 
DEFINT, DEFSNG, DEFDBL, DEFSTR, or 
DEF FN statements containing shared variables 
must be restated in the chained program. 

4. The CHAIN statement does a RESTORE before 
running the chained-to program. 
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CHDIR 

Command 



Purpose: Changes the current directory. (For BASIC 2.0 and 

later releases.) 

Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



CHDIR path 



path 



Example: 



is a string expression, not exceeding 63 
characters, identifying the new directory 
that will become the current directory. 
For more information on paths refer to 
"Naming Files" and "Tree-Structured 
Directories" in Chapter 3 of the BASIC 
Handbook. 



ROOT 



SALES 



ACCTING 



MIKE 



SHANNON CHELLE 



ALICE 
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CHDIR 

Command 



(The examples that follow refer to the tree structure 
shown on the previous page.) 

To change to the root directory from any 
subdirectory, use: 

CHDIR "\" 

To change to the directory ALICE from the root 
directory, use: 

CHDIR "SALES\MIKE\ALICE" 

To change to the directory CHELLE from the 
directory ACCTING, use: 

CHDIR "CHELLE" 

To change from the directory MIKE to the directory 
SALES, use: 

CHDIR ". ." 

To make SALES the current directory on the 
current drive (drive A) and INVENTORY the 
current directory on drive C, use: 

CHDIR "SALES" 
CHDIR "C: INVENTORY" 

The directory INVENTORY must exist on drive C. 
Now when you use filespec on drive A, it refers to 
the files in the directory SALES. When you use 
filespec on drive C, it refers to the files in the 
directory INVENTORY. 



24 



CHR$ 

Function 



Purpose: Converts an ASCII code to its character equivalent. 
Versions: Cassette Disk Advanced Compiler 



Format: v$ = CHR$(«) 

Remarks: n must be in the range to 255. 

The CHR$ function returns the one-character string 
with ASCII code n. ASCII codes are listed in 
Appendix D, "ASCII Character Codes." CHR$ is 
commonly used to send a special character to the 
screen or printer. For instance, the BEL character, 
which beeps the speaker, might be included as 
CHR$(7) as a preface to an error message (instead 
of using BEEP). See "ASC Function," earlier in this 
manual, for information on how to convert a 
character back to its ASCII code. 

Example: This example prints the character equivalent of 
ASCII code 66. 

PRINT CHR$(66) 



The next example sets function key F 1 to the string 
"AUTO" plus Enter. This is a good way to set the 
function keys so Enter is automatic when you press 
the function key. 

KEY 1,"AUT0"+CHR$(13) 
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CHR$ 

Function 



The following example is a program that shows all 
the displayable characters, along with their ASCII 
codes, on the screen in 80-column width. It can be 
used with either the IBM Monochrome Display and 
Parallel Printer Adapter or the Color/ Graphics 
Monitor Adapter. 

10 CLS 

20 FOR 1=1 TO 255 

30 ' ignore nondisplayable characters 

40 IF (I>6 AND I<14) OR (I>27 AND I<32) THEN 1{ 

50 COLOR 0,7 ' black on white 

60 PRINT USING "###"; I ; ' 3-digit ASCII code 

70 COLOR 7,0 ' white on black 

80 PRINT " "; CHR$(I); " "; 

90 IF POS(0)>75 THEN PRINT ' go to next line 

100 NEXT I 
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CINT 

Function 



Purpose: Converts jc to an integer. 

Versions: Cassette Disk Advanced Compiler 

Format: v = CINT(x) 

Remarks: 

x can be any numeric expression. If x is not in 

the range -32768 to 32767, an Overflow error 
occurs. 

jc is converted to an integer by rounding (up) the 
fractional portion. 

See "FIX" and "INT" functions, both of which also 
return integers. See "CDBL" and "CSNG" 
functions for converting numbers to single or double 
precision. 

Example: Observe in both examples how rounding occurs. 

PRINT CINK45.499) 
45 

PRINT CINK-2.89) 
-3 
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CIRCLE 

Statement 



Purpose: Draws an ellipse on the screen with center (x,y) and 
radius r. 

Versions: Cassette Disk Advanced Compiler 



Graphics mode only. 

Format: CIRCLE (x,y),r [,color [,start,end [,aspeci\\\ 

Remarks: 

(x,y) are the coordinates of the center of the 

ellipse. The coordinates can be given in 
either absolute or relative form. See 
"Specifying Coordinates" under 
"Graphics Modes" in Chapter 3 of the 
BASIC Handbook. 

r is the radius (major axis) of the ellipse 

in points. 

color is an integer expression that chooses a 

color attribute from the color attribute 
range for the current screen mode. In 
medium resolution, the color is the 
current one for that color attribute as 
defined by the COLOR statement. 
Four color attributes (0-3) are available 
in medium resolution; in high resolution, 
two attributes (0-1) are available. Zero 
(0) is always the color attribute for the 
background. The default foreground 
color attribute is always the maximum 
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start, end 



CIRCLE 

Statement 

color attribute for that screen mode: 3 
in medium resolution; 1 in high 
resolution. 

are angles in radians and can range from 
-2*PI to 2*PI, where PI=3. 141593. 



aspect 



is a numeric expression. 



start and end specify where the drawing of the ellipse 
will begin and end. The angles are positioned in the 
standard mathematical way, with to the right and 
going counterclockwise: 



PI/2 




0.2*PI 



3*PI/2 



If the start or end angle is negative (-0 is not 
allowed), the ellipse is connected to the center point 
with a line, and the angles are treated as if they were 
positive (note that this is not the same as adding 
2*PI). The start angle can be greater or less than the 
end angle. For example, 



10 PI=3. 141593 

20 SCREEN 1 

30 CIRCLE (160,1! 



), 60,, -PI, -PI/2 



draws a part of a circle similar to the following: 
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CIRCLE 

Statement 




aspect affects the ratio of the x-radius to the y-radius. 
The default for aspect is 5/6 in medium resolution 
and 5/12 in high resolution. These values give a 
visual circle assuming the standard screen aspect 
ratio of 4/3. 

If aspect is less than 1 , then r is the x-radius. That is, 
the radius is measured in points in the horizontal 
direction. If aspect is greater than 1 , then r is the 
radius. For example, 

10 SCREEN 1 

20 CIRCLE (160, 100), 60,,, ,5/18 

draws an ellipse like this: 




In many cases, an aspect of 1 results in nicer-looking 
circles in medium resolution. It also causes the circle 
to be drawn somewhat faster. 
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CIRCLE 

Statement 

The last point referenced after a circle is drawn is the 
center of the circle. 

Points that are off the screen are clipped. 

Example: The following example draws a face. 

10 PI=3. 141593 

20 SCREEN 1 ' medium res. graphics 

30 COLOR 0,1 ' black background, palette 1 

40 'two circles in color 1 (cyan) 

50 CIRCLE (120, 50), 10,1 

60 CIRCLE (200,50), 10,1 

70 'two horizontal ellipses 

80 CIRCLE (120,50), 30, ,,,5/18 

90 CIRCLE (200, 50), 30, ,,,5/18 

100 'arc in color 2 (magenta) 

110 CIRCLE (160,0), 150, 2, 1.3*PI, 1.7*PI 

120 'arc, one side connected to center 

130 CIRCLE (160,52) ,50, s 1.4*PI. -1.6*PI 
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CLEAR 
Command 



Purpose: Sets all numeric variables to zero and all string 

variables to null. Options set the maximum number 
of bytes that BASIC will address and the amount of 
stack space. 

Versions: Cassette Disk Advanced Compiler 

Format: CLEAR [,[«] [,m]] 
Remarks: 

n is a byte count that, if specified, sets the 

maximum number of bytes for the BASIC 
data segment (where your program and data 
are stored along with the interpreter work 
area). The default value for n is 65535. You 
can specify n as a smaller value to decrease 
BASIC'S total addressable space. This 
increases the amount of available memory 
beyond BASIC'S data segment in high 
memory. Include n if you need to reserve 
space in storage for assembly language 
programs beyond the BASIC data segment. 

m sets aside stack space for BASIC. The default 
is 512 bytes, or 1/8 of the available memory 
(whichever is smaller). Include m if you use 
many nested GOSUB statements or 
FOR... NEXT loops in your program, or if you 
use PAINT to do complex scenes. 

CLEAR frees all memory used for data without 
erasing the program currently in memory. After a 
CLEAR, arrays are undefined; numeric variables 
have a value of zero; string variables have a null 
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CLEAR 
Command 

value; and any information set with any DEF 
statement is lost. (This includes DEF FN, DEF 
SEG, and DEF USR, as well as DEFINT, DEFDBL, 
DEFSNG, and DEFSTR.) 

Executing a CLEAR command turns off any sound 
that is running and resets to Music Foreground. 
Also, PEN and STRIG are reset to OFF. 

The ERASE statement is useful to free some 
memory without erasing all the data in the program. 
It erases only specified arrays from the work area. 
See "ERASE Statement." 

Example: This example clears all data from memory (without 
erasing the program) : 

CLEAR 

The next example clears the data and sets the 
maximum data segment size to 32K bytes: 

CLEAR ,32768 

The next example clears the data and sets the size of 
the stack to 2000 bytes: 

CLEAR ,,2000 

The last example clears data, sets the maximum data 
segment for BASIC to 32K bytes, and sets the stack 
size to 2000 bytes: 

CLEAR ,32768,2000 
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CLOSE 

Statement 

Purpose: Concludes I/O to a device or file. 
Versions: Cassette Disk Advanced Compiler 

Format: CLOSE [[#] filenum [,[#] filenum]....] 

Remarks: 

filenum is the number used on the OPEN 
statement. 

The association between a particular file or device 
and its file number stops when CLOSE is executed. 
Subsequent I/O operations specifying that file 
number will be invalid. The file or device can be 
opened again using the same or a different file 
number; or the file number can be reused to open 
any device or file. 

A CLOSE to a file or device opened for sequential 
output causes the final buffer to be written to the file 
or device. 

A CLOSE with no file numbers specified causes all 
open devices and files to be closed. 

Executing an END, NEW, RESET, SYSTEM, or 
RUN without the R option causes all open files and 
devices to be automatically closed. STOP does not 
close any files or devices. 

See also "OPEN Statement" for information about 
opening files. 
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CLOSE 
Statement 

Example: This example causes the files and devices associated 
with file numbers 1 , 2, and 3 to be closed. 

100 CLOSE #1,#2,#3 

This example causes all open devices and files to be 
closed. 

100 CLOSE 
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CLS 

Statement 



Purpose: Clears the screen. 
Versions: Cassette Disk 



Advanced Compiler 



Format: CLS 

Remarks: If the screen is in text mode, the active page is 

cleared to the background color. See also "COLOR" 
and "SCREEN" statements. 

If the screen is in graphics mode (medium or high 
resolution), the entire screen buffer is cleared to the 
background color. 

The CLS statement also returns the cursor to the 
home position. In text mode, this means the cursor is 
located in the upper left-hand corner of the screen. 
In graphics mode, this means the "last point 
referenced" for future graphics statements is the 
point in the center of the screen: (160,100) in 
medium resolution; (320,100) in high resolution. 

Changing the screen mode or width by using the 
SCREEN or WIDTH statements also clears the 
screen. The screen can also be cleared by pressing 
Ctrl-Home. 

When you are using the VIEW statement, CLS clears 
only the last viewport. To clear the entire screen you 
must use VIEW to disable the active viewport, and 
then use CLS to clear the screen. (Viewports are 
used in BASIC 2.0 and later releases.) 
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CLS 

Statement 

Example: With the Color/Graphics Monitor Adapter, this 
example clears the screen to blue. 

10 SCREEN 0,0,0 
20 COLOR 10,1 
30 CLS 
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COLOR 
Statement 



Purpose: Sets the colors for the foreground, background, and 
border screen. See "Text Mode" in Chapter 3 of the 
BASIC Handbook for an explanation of these terms. 

The syntax of the COLOR statement depends on 
whether you are in text mode or graphics mode, as 
set by the SCREEN statement. 

When BASIC is first started, the color is initially set 
to white on black. 

In text mode, you can set the following: 

Foreground- 1 of 1 6 color attributes 

Character blink, if desired 
Background- 1 of 8 color attributes 
Border- 1 of 1 6 color attributes 

You can set the following in medium-resolution 
graphics mode: 

Background- 1 of 16 color attributes 
Palette- 1 of 2 palettes with 3 color attributes 

each 

The border is the same as the background color. 
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COLOR 
Statement 

The COLOR Statement in Text Mode 

Versions: Cassette Disk Advanced Compiler 

Format: COLOR [foreground] [,[background\ [,border\\ 

Remarks: 

foreground is a numeric expression in the range 
to 3 1 , representing the character 
color. 

background is a numeric expression in the 

range to 7 for the background 
color. 

border is a numeric expression in the range 

to 1 5 . It is the color for the border 
screen. 

If you have the Color/ Graphics Monitor Adapter, the 

following colors are allowed in foreground: 



Black 


8 Gray 


1 Blue 


9 Light Blue 


2 Green 


10 Light Green 


3 Cyan 


1 1 Light Cyan 


4 Red 


12 Light Red 


5 Magenta 


1 3 Light Magenta 


6 Brown 


14 Yellow 


7 White 


1 5 High-intensity White 



Colors and intensity can vary depending on your 
display device. 

You might like to think of colors 8 to 15 as "light" or 
"high-intensity" values of colors to 7. 
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COLOR 

Statement 



You can make the characters blink by setting 
foreground equal to 1 6 plus the number of the desired 
color. That is, a value of 16 to 31 causes blinking 
characters. 

You can select only colors through 7 for 
background in text mode. 

If you have the IBM Monochrome Display and Parallel 
Printer Adapter, the following values can be used for 
foreground: 

Black 

1 Underlined character with standard 
foreground color 

2-7 Standard foreground color 

With the Color/Graphics Monitor, adding 8 to the 
number of the desired color gives you the color in 
high intensity. For example, an attribute of 15 gives 
you the standard color in high intensity. 

With the Color/Graphics Monitor Adapter, you can 
make the character blink by adding 1 6 to the 
attribute. Thus, 3 1 gives you high-intensity standard 
color characters. 

For background with the IBM Monochrome Display 
and Parallel Printer Adapter, you can select the 
following values: 

0-6 Black 

7 Standard foreground color 

Note: Attribute 7 as a background attribute 
appears as the standard color on the IBM 
Monochrome Display only when it is used with a 
foreground attribute of 0, 8, 16, or 24 (black). 
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Statement 

Conversely, black (attribute 0, 8, 16, or 24) as a 
foreground attribute shows up as black only when 
used with a background attribute that creates 
reverse image characters. Black used with a 
background attribute of makes the characters 
invisible. 

Other combinations of foreground and 
background attributes produce standard results 
on the IBM Monochrome Display. 

Notes for either adapter: 

1 . Foreground attribute can equal background 
attribute. This makes any character displayed 
invisible. Changing the foreground or 
background attribute makes subsequent 
characters visible again. 

2. Any parameter can be omitted. Omitted 
parameters assume the old value. 

3. If the COLOR statement ends in a comma (,), 
you get a Missing operand error, but the color 
changes. For example, 

COLOR 1,7, 

is invalid. 

4. Any values entered outside the range to 255 
result in an Illegal function call error. Previous 
values are retained. 

Example: This statement sets a yellow foreground, a blue 
background, and a black border screen. 

10 COLOR 14,1,0 
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The following example can be used with either the 
Color/Graphics Monitor Adapter or the IBM 
Monochrome Display and Parallel Printer Adapter: /' 

10 PRINT "Enter your "; 

20 COLOR 15,0 'highlight next word 

30 PRINT "password"; 

40 COLOR 7 'return to default (white on black) 

50 PRINT " here: "; 

60 COLOR 'invisible (black on black) 

70 INPUT PASSWORDS 

80 IF PASSWORD$="secret" THEN 120 

90 ' blink and highlight error message 

100 COLOR 31: PRINT "Wrong Password": COLOR 7 

110 GOTO 10 

120 COLOR 0,7 'reverse image (black on white) 

130 PRINT "Program continues..."; 

140 COLOR 7,0 'return to default (white on black) 
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Statement 

The COLOR Statement in Graphics Mode 



Versions: Cassette Disk 



Advanced Compiler 



Format: 
Remarks: 



Graphics mode, medium resolution only. 
COLOR [background] [,[palette]] 



background is an integer expression in the range 
through 15. It specifies the 
background attribute. 



palette 



is an integer expression. It selects 
one of two palettes of color. 



In graphics mode, the COLOR statement sets a 
background color and chooses one of two palettes 
with four color attributes each (0-3). Color 
attribute is always the current background. You 
can select one of three color attributes for the 
foreground color to be used with PSET, PRESET, 
LINE, CIRCLE, PAINT, VIEW, and DRAW. The 
COLOR statement in graphics mode has meaning 
only for medium resolution. Using COLOR in high 
resolution results in in an Illegal function call error. 
The colors selected when you choose each palette are 
as follows: 

Color Palette Palette 1 

1 Green Cyan 

2 Red Magenta 

3 Brown White 
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If palette is an even number, palette is selected. 
This associates the colors green, red, and brown to 
the color attributes 1,2, and 3. 

If palette is an odd number, palette 1 
(cyan/magenta/ white) is selected. 

Graphics mode can display text in any of the three 
colors available in the current palette. However, if 
you are not using a U.S. keyboard, refer to the 
"GRAFT ABL Command" in Disk Operating System 
Reference for information regarding additional 
character support for the Color/Graphics monitor 
adapter and other keyboards. 

You can change the foreground color of the 
characters from 3 to 2 to 1 by entering: 

DEF SEG: POKE &HFE, COLOR 

where COLOR is the attribute 1, 2, or 3; is not 
allowed. Later PRINTs will use the specified color 
attribute. 

The color selected for background can be the same 
as any of the palette colors. 

Any parameter can be omitted from the COLOR 
statement. Omitting parameters will not cause the 
current background or palette to change. 

Any values entered outside the range to 255 cause 
an Illegal function call error. Previous values are 
retained. 
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Statement 

Example: This statement sets the background to light blue and 
selects palette 0. 

10 SCREEN 1 
20 COLOR 9,0 

In the next example, the background stays light 
blue, and palette 1 is selected. 

10 COLOR ,1 
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COM(n) 
Statement 



Purpose: Enables or disables trapping of communications 
activity to the specified communications adapter. 

Versions: Cassette Disk Advanced Compiler 

Format: COM(«) ON 

COM(n) OFF 

COM(n) STOP 
Remarks: 

n is the number of the communications adapter 

(lor 2). 

A COM(«) ON statement must be executed to allow 
trapping by the ON COM(«) statement. If a 
nonzero line number is specified in the ON COM(n) 
statement, BASIC checks every time a new 
statement is executed to see if any characters have 
come in to the communications adapter. 

If COM(n) is OFF, no trapping takes place, and any 
communication activity is not remembered even if it 
does take place. 

If a COM(n) STOP statement has been executed, no 
trapping can take place. However, any 
communications activity that does take place is 
remembered so that an immediate trap occurs when 
COM(n) ON is executed. 
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Statement 



Purpose: 
Versions: 

Format: 
Remarks: 



Example: 



Passes variables to a chained program. 
Cassette Disk Advanced Compiler 

*** *** (**"\ 

COMMON variable[,variable]... 



variable is the name of a variable that to be 
passed to the chained-to program. 
Arrays are specified by appending "()" 
to the array name. 

The COMMON statement is used with the CHAIN 
statement. COMMON statements can appear 
anywhere in a program, although it is recommended 
that they appear at the beginning. Any number of 
COMMON statements can appear in a program, but 
the same variable cannot appear in more than one 
COMMON statement. If all variables are to be 
passed, use CHAIN with the ALL option and omit 
the COMMON statement. 

Any arrays that are passed do not need to be 
dimensioned in the chained-to program. 

This example chains to program PROG3 on the disk 
in drive A, and passes the array D along with the 
variables A, BEE1, C, and G$. 

100 COMMON A,BEE1,C,D(),G$ 

110 CHAIN "A:PR0G3" 
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CONT 
Command 

Purpose: Resumes program execution after a break. 
Versions: Cassette Disk Advanced Compiler 

Format: CONT 

Remarks: The CONT command can be used to resume 
program execution after Ctrl-Break has been 
pressed; a STOP or END statement has been 
executed; or an error has occurred. Execution 
continues at the point where the break occurred. If 
it occurred after a prompt from an INPUT 
statement, execution continues with the reprinting of 
the prompt. 

CONT is usually used with STOP for debugging. 
When execution is stopped, you can examine or 
change the values of variables by using direct mode 
statements. You can then use either CONT to 
resume execution, or a direct mode GOTO to resume 
execution at a particular line number. 

CONT is invalid if the program has been edited 
during the break. 
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Example: The following example creates a long loop. 

10 FOR A=l TO 50 

zy PRINT a; 

30 NEXT A 

RUN 
1 2 3 4 5 6 7 8 9 10 11 12 
13 14 15 16 17 18 19 20 21 22 
23 24 25 26 27 28 29 

(At this point we interrupt the loop by pressing 
Ctrl-Break.) 



Break in 20 

CONT 
30 31 32 33 34 35 36 37 38 39 
40 41 42 43 44 45 46 47 48 49 

50 
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COS 
Function 



Purpose: Returns the trigonometric cosine function. 
Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



Example: 



v = COS(x) 



x is the angle whose cosine is to be calculated. 

The value of x must be in radians. To convert 
from degrees to radians, multiply the degrees 
by PI/180, where PI=3. 141593. 

In BASIC 2.0 and later releases, you can have this 
calculation performed in double-precision by 
specifying /D in the BASIC command line when 
BASIC is initially loaded. See "Options in the 
BASIC Command" in BASIC Handbook. 

This example shows that the cosine of PI radians is 
equal to -1. Then it calculates the cosine of 180 
degrees by first converting the degrees to radians 
(180 degrees happens to be the same as PI radians). 

10 PI=3. 141593 

20 PRINT COS(PI) 

30 DEGREES=180 

40 RADIANS=DEGREES*PI/180 

50 PRINT COS(RADIANS) 

RUN 

-1 

-1 
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Function 



Purpose: Converts x to a single-precision number. 



Versions: Cassette Disk 



Advanced Compiler 



Format: 
Remarks: 



v = CSNG(x) 



x is a numeric expression that will be converted 

to single precision. 

The rules outlined under "How BASIC Converts 
Numbers from One Precision to Another" in 
Chapter 3 of the BASIC Handbook are used for the 
conversion. 

See also "CINT" and "CDBL" functions for 
information on converting numbers to the integer 
and double-precision data types. 

Example: In this example the value of the double-precision 

number A# is rounded at the 7 th digit and returned 

as CSNG(A#). 

10 A# = 975.3421222# 
20 PRINT A#; CSNG(A#) 
RUN 
975.3421222 975.3421 
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CSRLIN 

Variable 



Purpose: Returns the vertical coordinate of the cursor. 
Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



Example: 



v = CSRLIN 

The CSRLIN variable returns the current line (row) 
position of the cursor on the active page. The active 
page is explained under "SCREEN Statement." The 
value returned is in the range 1 to 25. 

The POS function returns the column location of the 
cursor. See "POS Function." 



See also "LOCATE Statement' 
cursor line. 



to see how to set the 



This example saves the cursor coordinates in the 
variables X and Y, then moves the cursor to line 24 
to put the words "HI MOM" on that line. Then the 
cursor is moved back to its former position. 

10 Y = CSRLIN 'record current line 
20 X = POS (0 ) 'record current column 
30 LOCATE 24,1: PRINT "HI MOM" 
40 LOCATE Y 5 X 'restore position 
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CVI, CVS, CVD 
Functions 



Purpose: Converts string variable types to numeric variable 
types. 

Versions: Cassette Disk Advanced Compiler 

Format: v = CWl(2-byte string) 

v = CVS(4-byte string) 

v = CVD(8-byte string) 

Remarks: Numeric values read from a random file must be 

converted from strings into numbers. CVI converts 
a 2-byte string to an integer. CVS converts a 4-byte 
string to a single-precision number. CVD converts 
an 8-byte string to a double-precision number. 

The CVI, CVS, and CVD functions do not change 
the bytes of the actual data. They change only the 
way BASIC interprets those bytes. 

See also "MKI$, MKS$, MKD$ Functions," as well 
as Appendix A, "BASIC Disk Input and Output," in 
the BASIC Handbook. 
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CVI, CVS, CVD 

Functions 

Example: This example uses a random file (#1), which has 

fields defined as in line 100. Line 110 reads a record 
from the file. Line 120 uses the CVS function to 
interpret the first 4 bytes (N$) of the record as a 
single-precision number. N$ was probably originally 
a number that was written to the file using the MKS$ 
function. 

100 FIELD #1,4 AS N$, 12 AS B$ 
110 GET #1 
120 Y=CVS(N$) 



54 



DATA 

/Statement 



Purpose: 



Versions: 



Stores the numeric and string constants that are 
accessed by a program's READ statements. 



Cassette 
*** 



Disk 

*** 



Advanced 

*** 



Compiler 

*** 



Format: DATA constant[,constant]... 
Remarks: 

constant can be a numeric or string constant. No 
expressions are allowed in the list. The 
numeric constants can be in any format 
- integer, fixed point, floating point, 
hex, or octal. String constants in DATA 
statements do not have to be enclosed 
by quotation marks, unless the string 
contains commas, colons, or significant 
leading or trailing blanks. 

DATA statements are nonexecutable and can be 
placed anywhere in the program. A DATA 
statement can contain as many constants as will fit 
on a line, and any number of DATA statements can 
be used in a program. The information contained in 
the DATA statements can be thought of as one 
continuous list of items, regardless of how many 
items are on a line or where the lines are placed in 
the program. The READ statements access the 
DATA statements in line-number order. 

The variable type (numeric or string) in the READ 
statement must agree with the corresponding 
constant in the DATA statement or a Syntax error 
occurs. 
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DATA 

Statement 

You cannot use the single quote (') to add comments 
to the end of a DATA statement. If you do, BASIC 
thinks it is part of a string. You can, however, use 
:REM to add a remark. 

Use the RESTORE statement to reread information 
from any line in the list of DATA statements. See 
"RESTORE Statement." 

Example: See examples under "READ Statement." 
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DATES Variable and 
Statement 



Purpose: Sets or retrieves the date. 

Versions: Cassette Disk Advanced Compiler 

Format: As a variable: 

v$ = DATE$ 
As a statement: 

DATES = x$ 

Remarks: For the variable (v$ = DATE$): 

A 1 0-character string in the form mm-dd-yyyy is 
returned. Here, mm represents 2 digits for the 
month, dd is the day of the month (also 2 digits), and 
yyyy is the year. The date can have been set by DOS 
before entering BASIC. 

For the statement (DATES = x$): 

x$ is a string expression used to set the current date. 
You can enter x$ in any one of the following forms: 

mm-dd-yy 
mm/dd/yy 
mm-dd-yyyy 
mm/dd/yyyy 

The year must be in the range 1980 to 2099. If you 
use only one digit for the month or day, a (zero) is 
assumed in front of it. If you enter only 1 digit for 
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DATES Variable and 
Statement 

the year, a zero is appended to make it 2 digits. If 
you enter only 2 digits for the year, the year is 
assumed to be 1 9yy. 

Example: In this example we set the date to August 29, 1984. 
Notice how, when we read the date back using the 
DATE$ function, a zero is included in front of the 
month to make it 2 digits, and the year becomes 
1984. Also, the month, day, and year are separated 
by hyphens even though we enter them as slashes. 

10 DATE$= "8/29/84" 
20 PRINT DATE$ 
RUN 08-29-1984 
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DEFFN 

Statement 



Purpose: Defines and names a function that you write. 



Versions: Cassette Disk 



Advanced Compiler 



Format: DEF FNname[(arg [,arg]...)] ^expression 
Remarks: 

name is a valid variable name. This name, 

preceded by FN, becomes the name 
of the function. 

arg is an argument. It is a variable name 

in the function definition that is 
replaced with a value when the 
function is called. The arguments in 
the list represent, on a one-to-one 
basis, the values that are given when 
the function is called. 

expression defines the returned value of the 

function. The type of the expression 
(numeric or string) must match the 
type declared by name. 

The definition of the function is limited to one 
statement. Arguments (arg) that appear in the 
function definition serve only to define the function; 
they do not affect program variables that have the 
same name. A variable name used in the expression 
does not have to appear in the list of arguments. If it 
does, the value of the argument is supplied when the 
function is called. Otherwise, the current value of 
the variable is used. 
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DEFFN 

Statement 

The function type determines whether the function 
returns a numeric or string value. The type of 
function is declared by name, in the same way as 
variables are declared. See "How to Declare Variable 
Types" in Chapter 3 of the BASIC Handbook. If the 
type of expression (string or numeric) does not match 
the function type, a Type mismatch error occurs. If 
the function is numeric, the value of the expression is 
converted to the precision specified by name before 
it is returned to the calling statement. 

A DEF FN statement must be executed to define a 
function before you can call that function. If a 
function is called before it has been defined, an 
Undefined user function error occurs. On the other 
hand, a function can be defined more than once. 
The most recently executed definition is used. 

Recursive functions are not supported. 

DEF FN is invalid in direct mode. 

Example: In this example, line 20 defines the function 

FNAREA, which calculates the area of a circle with 
radius R. The function is called in line 40. 

10 PI=3. 141593 

20 DEF FNAREA(R)=PI*Ra2 

30 INPUT "Radius? ", RADIUS 

40 PRINT "Area is " FNAREA(RADIUS) 

RUN 

Radius? 

(Suppose you respond with 2) 

Radius? 2 

Area is 12.56637 
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DEFFN 

Statement 

Here is an example with two arguments: 

10 DEF FNMUD(X.Y)=X-(INT(X/Y)*Y) 
20 A = FNMUD(7.4,4) 
30 PRINT A 
RUN 
3.4 
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DEF SEG 

Statement 



Purpose: Defines the current segment of memory. A 

subsequent BLOAD, BSAVE, CALL, PEEK, 
POKE, or DEF USR definition specifies the offset 
into this segment. 

Versions: Cassette Disk Advanced Compiler 



Format: DEF SEG [^segment] 
Remarks: 



segment is a numeric expression in the range to 
65535. 

The initial setting for the segment when BASIC is 
started is BASIC'S data segment (DS). BASIC'S 
data segment is the beginning of your user workspace 
in memory. If you execute a DEF SEG statement 
that changes the segment, the value is not reset to 
BASIC'S DS when you issue a RUN command. 

If segment is omitted from the DEF SEG statement, 
the segment is set to BASIC'S data segment. The 
value of BASIC'S data segment can be found in 
segment 0, offsets &H510 and &H511. 

If segment is given, it should be a value based upon a 
16-byte boundary, since segments begin only on 
paragraph boundaries. The value is shifted left 4 bits 
(multiplied by 16) to form the segment address for 
the subsequent operation. That is, if segment is in 
hexadecimal, a (zero) is added to get the actual 
segment address. BASIC does not perform any 
checking to ensure that the segment value is valid. 
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DEF SEG 

Statement 

DEF and SEG must be separated by a space; 
otherwise, BASIC interprets the statement 
DEFSEG=100 to mean "Assign the value 100 to 
the variable DEFSEG." 

Any value entered outside the range indicated results 
in an Illegal function call error. The previous value is 
retained. 

See also Appendix B, "Assembly Language 
Subroutines," for more information on using DEF 
SEG. 

Example: The first example restores a segment to BASIC'S 
data segment. 

DEF SEG ' restore segment to BASIC'S data segmer 

In the second example, the screen buffer for the 
Color/Graphics Monitor adapter is at segment B800 
hex, offset 0. Since segments are specified on 
16-byte boundaries, thf last hex digit is dropped on 
the DEF SEG specification. 

DEF SEG= 
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DEFtype 
Statements 



Purpose: Declares variable types as integer, single-precision, 
double-precision, or string. 

Versions: Cassette Disk Advanced Compiler 

Format : DEFtype letter[ - letter] [ , letter [ - letter] ]... 
Remarks: 

type is INT, SNG, DBL, or STR. 

letter is a letter of the alphabet (A-Z). 

A DEFtype statement declares that the variable 
names beginning with the letter or letters specified 
will be that type of variable. However, a 
type-declaration character (%,!,#, or $) always 
takes precedence over a DEFtype statement in the 
typing of a variable. See "How to Declare Variable 
Types" in Chapter 3 of the BASIC Handbook. 

If no type-declaration statements are encountered, 
BASIC assumes that all variables without declaration 
characters are single-precision variables. 

If you use type-declaration statements, put them at 
the beginning of the program. The DEFtype 
statement must be executed before you use any 
variables it declares. 
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DEFtype 

Statements 

Example: In this example, line 10 declares that all variables 
beginning with the letter L, M, N, O, or P are 
double-precision variables. 

Line 20 causes all variables beginning with the letter 
A to be string variables. 

Line 30 declares that all variables beginning with the 
letter X, D, E, F, G, or H are integer variables. 

10 DEFOBL I..-P 

20 DEFSTR A 

30 DF.FINT X,P--H 

40 ORDER - l#/3; PRINT ORDER 

50 ANIMAL - "CAT": PRINT ANIMAL 

60 X; 10/3: PRINT X 

RUN 

.3333333333333333 
CAT 
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DEF USR 

Statement 



Purpose: 



Versions: 



Specifies the location in memory of an assembly 
language subroutine, which is later called by the USR 
function. 



Cassette 

*** 



Disk 



Advanced 

*** 



Compiler 

*** 



Format: DEF USR[n]= offset 
Remarks: 



n must be a digit from to 9. It identifies 

the number of the USR routine whose 
location in memory is being specified. If n 
is omitted, DEF USR0 is assumed. 

offset is an integer expression in the range to 
65535. The value of offset is added to the 
current segment value to obtain the actual 
starting address of the USR routine. See 
"DEF SEG Statement." 

Any number of DEF USR statements can appear in a 
program, thus allowing access to as many subroutines 
as necessary. The most recently executed value is 
used for the offset. 
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DEF USR 

Statement 

Example: This example loads an assembly language subroutine 
into an integer array. The n in iine 60 is determined 
by the size of the subroutine. The offset passed to 
DEF USR is the offset into BASIC'S data segment. 

10 OPTION BASE 1 

20 DEFINT A-Z 

30 'Define all variables before VARPTR 

40 SUBRT=0: 1=0: J=0 

50 'Dimension array for subroutine 

60 DIM ARRAY (n) 

70 'Obtain offset of 1st array element into 

BASIC'S data segment 
80 SUBRT = VARPTR(ARRAY(D) 
90 'Load routine into the integer array 
100 BLOAD "ASMFILE", SUBRT 



1000 'Pass offset to DEF USR 
1010 DEF USR0 = VARPTR(ARRAY(D) 
1020 'Execute the subroutine 
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DELETE 

Command 



Purpose: 
Versions: 



Deletes program lines. 

Cassette Disk Advanced Compiler 



Format: 



Remarks: 



DELETE [Uriel] [-line2] 
DELETE [Uriel-] 



Uriel is the line number of the first line to be 

deleted. 

Hne2 is the line number of the last line to be 

deleted. 

The DELETE command erases the specified range of 
lines from the program. BASIC always returns to 
command level after a DELETE is executed. 

DELETE Uriel- deletes all lines from the specified 
line number through the end of the program. This 
form is valid for BASIC 2.0 and later releases. 

A period (.) can be used in place of the line number 
to indicate the current line. If you specify a line 
number that does not exist in the program, an Illegal 
function call error occurs. 

Example: This example deletes line 40: 

DELETE 40 
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DELETE 

Command 

This example deletes lines 40 through 100, 
inclusive: 

DELETE 40-100 

This example deletes line 40 through the end of the 
program: 

DELETE 40- 

The last example deletes all lines up to and including 
line 40: 

DELETE -40 
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DIM 

Statement 



Purpose: Specifies the maximum values for array variable 
subscripts and allocates storage accordingly. 



Versions: Cassette Disk 



Advanced Compiler 



Format: DIM variable(subscripts)[,variable(subscripts)]... 

Remarks: 

variable is the name used for the array. 

subscripts is a list of numeric expressions, 

separated by commas, which define 
the dimensions of the array. 

When executed, the DIM statement sets all the 
elements of the specified numeric arrays to an initial 
value of zero. String array elements are all variable 
length, with an initial null value (zero length). 

If an array variable name is used without a DIM 
statement, the maximum value of its subscript is 
assumed to be 10. If a subscript is greater than the 
maximum specified, a Subscript out of range error 
occurs. 

The minimum value for a subscript is always 0, 
unless otherwise specified with the OPTION BASE 
statement. (See "OPTION BASE Statement.") The 
maximum number of dimensions for an array is 255. 

If you try to dimension an array more than once, a 
Duplicate definition error occurs. You can, however, 
use the ERASE statement to erase an array so you 
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DIM 

Statement 

can dimension it again. For more information about 
arrays, see "Arrays" in Chapter 3 of the BASIC 
Handbook. 

Example: This example creates two arrays: a one-dimensional 
numeric array named SIS with 13 elements, SIS(0) 
through SIS(12); and a two-dimensional string array 
named WRR$, with three rows and three columns. 

10 WRRMAX=2 

20 DIM SISC12), WRR$(WRRMAX,2) 
30 DATA 26.5, 37, 8, 29, 80, 9.9, &H800 
40 DATA 7, 18, 55, 12, 5, 43 
50 FOR 1=0 TO 12 
60 READ SIS(I) 
70 NEXT I 

80 DATA SHERRY, ROBERT, "A:" 
90 DATA "HI, LYNN", HELLO, GOOD-BYE 
100 DATA BOCA RATON, DELRAY, MIAMI 
110 FOR 1-0 TO 2: FOR J=0 TO 2 
120 READ WRR$(I,J) 
130 NLXT J,l' 

140 PRINT SIS(3); WRR$(2,0) 
RUN 
29 BOCA RATON 
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DRAW 

Statement 

Purpose: Draws an object as specified by string. 

Versions: Cassette Disk Advanced Compiler 

*** s**\ 

Graphics mode only. 

Format: DRAW string 

Remarks: The DRAW statement draws objects using a graphics 
definition language. The language commands are 
contained in the string expression string. The string 
defines an object, which is drawn when BASIC 
executes the DRAW statement. During execution, 
BASIC examines the value of string and interprets 
single-letter commands from the contents of the 
string. When a movement command is given, a line is 
drawn from the last point referenced. 

n in the following movement commands indicates the 
distance to move. The number of points moved is n 
times the scaling factor (set by the S command). 
The movement commands are detailed on the next 
page. 
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DRAW 

Statement 

U n Move up. 

D n Move down. 

L n Move left. 

R n Move right. 

E n Move diagonally up and right. 

F n Move diagonally down and right. 

G n Move diagonally down and left. 

H n Move diagonally up and left. 



M x,y Move absolute or relative. If x has a plus 
sign ( + ) or a minus sign (-) in front of it, 
it is relative. Otherwise, it is absolute. 

The following two prefix commands can 
precede any of these movement 
commands: 

B Move, but don't plot any points. 

N Move, but return to the original position 

when finished. 

The following commands are also available: 

A n Set angle n. The value of n can range 

from to 3, where is degrees, 1 is 90, 
2 is 180, and 3 is 270. Figures rotated 90 
or 270 degrees are scaled so they appear 
the same size with or 180 degrees on a 
display screen with standard aspect ratio 
4/3. 
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DRAW 

Statement 



TAn 



Cn 



Sn 



Turn angle n. The value of n can range 
from -360 to +360. If n is positive (+), 
the angle turns counterclockwise. If n is 
negative (-), the angle turns clockwise. 
Values entered that are outside of the 
range -360 to +360 cause an Illegal 
function call error. This command is valid 
for BASIC version 2.0 and later releases. 

Set color n. The value of n can range 
from to 3 in medium resolution, and to 
1 in high resolution. In medium 
resolution, n selects the color attribute 
from the current palette as defined by the 
COLOR statement. Zero (0) is always 
the attribute for the background. The 
default foreground color attribute is 
always the maximum attribute for that 
screen mode: 3 in medium resolution; 1 in 
high resolution. 

Set scale factor. The value of n can range 
from 1 to 255. The scale factor is n 
divided by 4. For example, if n= 1, then 
the scale factor is 1/4. The scale factor 
multiplied by the distances given with the 
U, D, L, R, E, F, G, H, and relative M 
commands gives the actual distance 
moved. The default value is 4, so the scale 
factor is 1 . 



X variable; 



Execute substring. This allows you to 
execute a second string from within a 
string. 
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DRAW 

Statement 

P paint, boundary 

Set figure color to paint and border color 
to boundary. The paint parameter is an 
integer expression. It chooses an attribute 
from the attribute range for the current 
screen mode. In medium resolution, this 
color is one from the current palette as 
defined for that attribute by the COLOR 
statement. Four color attributes (0-3) are 
available in medium resolution. In high 
resolution, two color attributes (0-1) are 
available: indicates black and 1 
indicates white. The boundary parameter 
is the border color of the figure to be filled 
in, in the attribute range for the current 
screen mode. You must specify both paint 
and boundary, or an error occurs. This 
command does not support paint tiling, 
and it is valid for BASIC 2.0 and later 
releases. 

In all these commands, the n, x, or y argument can be 
a constant such as 123 or it can be = variable; where 
variable is the name of a numeric variable. The 
semicolon (;) is required when you use a variable this 
way, or in the X command. Otherwise, a semicolon 
is optional between commands. Spaces are ignored 
in string. For example, you can use variables in a 
move command this way: 
M+=X1; -=X2; 

You can also specify variables in the form 
VARPTR$ (variable), instead of = variable;. This is 
the only form that can be used in compiled programs. 
For example: 
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DRAW 

Statement 

One Method Alternative Method 

DRAW "XA$;" DRAW "X"+VARPTR$(A$) 
DRAW "S = SC;" DRAW "S="+VARPTR$(SC) 

The X command can be a very useful part of DRAW. 
It allows you to define segments of a picture in 
different X variables and to combine these X 
variables into a single DRAW statement. In this way 
you are able to create DRAW strings longer than 
255 characters. For example, if you are creating a 
scene of a house with a chimney and a tree, each of 
these objects can be defined in an X variable so your 
DRAW statement can look like this: 

DRAW "XHOUSE$;XCHIM$;XTREE$;" 

The aspect ratio of your screen determines the 
spacing of the horizontal, vertical, and diagonal 
points. The DRAW statement does not take into 
account the aspect ratio of the current screen mode; 
that is, DRAW "R50 U50" plots exactly 50 points 
to the right and then 50 up, but the two lines will not 
appear to be equal in length. 

The aspect ratio is used to correct the shape of 
objects drawn on a nonlinear surface. The idea is to 
be able to draw a square, for example, that indeed 
looks square. 



76 



DRAW 

Statement 

If there are 640 by 640 dots on a screen evenly 
spaced along the x and y axes, the aspect ratio is "1 
to 1" or 1/1. This is an ideal surface. If you execute 
the statement: 

DRAW "R100 D100 L100 U100" 

then the box appears square. 



However, this is not the case in BASIC, which 
supports two screen resolutions, each with its own 
aspect ratio. These are: 

Resolution Aspect Ratio 

Medium resolution 320 by 200 dots 5/6 
High resolution 640 by 200 dots 5/12 

To draw a box that appears square in either 
resolution, scale the y axis by the corresponding 
aspect ratio; or scale the x axis by 1 /aspect ratio. 

For example, to draw a square box 100 high, scale 
the x axis as follows: 

10 ! 100*6/5 is i20 

20 DRAW "U100 R120 D100 L120" 
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DRAW 

Statement 

Example: To draw a box using variables: 

10 SCREEN 1 

20 A=2030 DRAW "U=A;R=A;D=A;L=A; " 

To draw a box and paint the interior: 

10 DRAW "U50R50D50L50" 'Draw a box 

20 DRAW "BE10" 'Move up and right into box 

30 DRAW "PI, 3" 'Paint interior 

To draw a triangle: 

10 SCREEN 1 

20 DRAW "E15 F15 L30" 

To create a "shooting star": 

10 SCREEN 1,0: COLOR 0,0: CLS 

20 DRAW "BM300,25" ' initial point 

30 STAR$= "M+7,17 M-17,-12 M+20,0 M-17,12 M+7,-17" 

40 FOR SCALE=1 TO 40 STEP 2 

50 DRAW "C1;S=SCALE; BM-2,0;XSTAR$; " 

60 NEXT 

To draw some spokes: 

10 SCREEN 1,0:CLS 

20 FOR D=0 TO 360 STEP 10 

30 DRAW "TA=D; NU50" 

40 NEXT D 
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EDIT 

Command 



Purpose: 


Displays a line for editing. 


Versions: 


Cassette Disk Advanced 




*** *** *** 



Compiler 



Format: EDIT line 



Remarks: 



line is the line number of a line existing in the 
program. If there is no such line, an 
Undefined line number error occurs. 

EDIT simply displays the line specified and positions 
the cursor under the first digit of the line number. 
The line can then be modified as described under 
"The BASIC Program Editor" in the BASIC 
Handbook. 

A period (.) can be used for the line number to refer 
to the current line. For example, if you have just 
entered a line and wish to go back and change it, the 
command EDIT redisplays the line for editing. 

LIST can also be used to display program lines for 
changing. See "LIST Command." 
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END 

Statement 



Purpose: Terminates program execution, closes all files, and 
returns to command level. 

Versions: Cassette Disk Advanced Compiler 

Format: END 

Remarks: END statements can be placed anywhere in the 

program to terminate execution. END is different 
from STOP in two ways: 

• END does not cause a Break message to be 
printed. 

• END closes all files. 

An END statement at the end of a program is 
optional. BASIC always returns to command level 
after an END is executed. 

Example: This example ends the program if K is greater than 
1000; otherwise, the program branches to line 
number 20. 

100 IF K>1000 THEN END ELSE GOTO 20 
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ENVIRON 

Statement 



Purpose: Modifies parameters in BASIC'S environment table. 
ENVIRON is used to change the "PATH" parameter 
for a child process or to pass parameters to a child 
process by inventing a new environment parameter. 
See ENVIRONS, SHELL, and the DOS PATH 
Command. 

Not valid for releases earlier than 3.0. 



Versions: Cassette 



Disk Advanced Compiler 



Format: ENVIRON parm = string 

Remarks: 

parm is the name of the parameter, such as 
"PATH". 

string is the text that defines the new parameter. 

parm must be separated from string by an 
equal sign or a blank. ENVIRON takes 
everything left of the first blank or equal 
sign as parm. The first "nonblank, 
nonequal" after parm is taken as string. 

If string is a null string or consists only of 
";" (a single semicolon), such as: 

"PATH-;" 

the parameter is removed from the 
environment table and the table is 
compressed. 
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ENVIRON 

Statement 

If parm does not exist, the new parameter 
is added at the end of the environment 
table. 

If parm exists, it is deleted, the 
environment table is compressed, and 
parm is added at the end. 

Note: When BASIC is invoked, the 
size of its environment table is the 
current size of DOS's environment 
table (rounded up to the next 16-byte 
paragraph boundary.) BASIC cannot 
expand its environment table. If you 
wish to add elements to BASIC'S 
environment table, you must expand 
the table from DOS to the size your 
application needs before invoking 
BASIC. 

Example: You can create a default PATH to the root directory 
on drive A with the following statement: 

ENVIRON "PATH=A:\" 

Now, you can invoke DOS from your BASIC 
program using the SHELL statement and issue any 
valid DOS command. If a disk file is needed to 
execute the command, DOS now automatically 
searches for it (.COM, .EXE, or .BAT) in the root 
directory on drive A if it is not on the current drive 
or directory. 
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ENVIRON 
Statement 

SHELL 'Invokes a copy of C0MMAND.COM. 

A> REM Changes directory to "WORK" on drive B. 

A> CD B:\W0RK 

B> REM Loads PR0J1 under DEBUG even though no 

drive is specified. DEBUG and PR0J1 are 

located on different drives. 
B> DEBUG PR0J1 



B> REM Return to BASIC program 

B> EXIT (exit DOS, return to BASIC program.) 

You can add a new parameter to the environment 
table: 

ENVIRON "HELP = C:\HELP" 'defines 

file parameter called "HELP" 
CHDIR ENVIRONS ("HELP") 'chanqes dir to "HELP" 

You can delete this parameter in the table by: 



ENVIRON "HELP=;" 'deletes parameter "HELP" 

from table 

The environment you create from your BASIC 
application is passed to COMMAND.COM when it 
is invoked by the SHELL statement. This makes it 
possible to pass parameters from a parent (BASIC) 
to a child through the environment table. 

Note: For related information, see also 
"ENVIRONS Function" and "SHELL 
Statement" in this manual. Also "SET 
Command" in Disk Operating System Reference 
and the "EXEC Function Call" in Disk Operating 
System Technical Reference 
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ENVIRONS 

Function 



Purpose: Retrieves and displays the specified string from 
BASIC'S environment table. 

Not valid for BASIC releases earlier than 3.0. 
Versions: Cassette 



Disk 

*** 



Advanced Compiler 



Format: 



Remarks: 



v$ = ENVIRONS {parm) 

or 
v$ = ENVIRONS (/i) 



parm is a string expression containing 

the parameter to be retrieved. 

n is an integer expression returning 

a value in the range 1 to 255. 

If a string argument is used, ENVIRONS returns, 
from the environment table, a string containing the 
text that follows parm. If parm is not found or no 
text follows the equal sign, the null string is returned. 

If a numeric argument is used, ENVIRONS returns a 
string containing the nth parm from the environment 
table, along with the parm= text. If there is no nth 
parm, a null string is returned. 

ENVIRONS distinguishes between uppercase letters 
and lowercase letters. If you add to the table in this 
format: 
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ENVIRONS 
Function 

ENVIRONS "load = high" 

and want to check to see if the operation was 
successful, you can use the ENVIRONS function like 
this: 

PRINT ENVIRON ("load") 
But if you type: 

PRINT ENVIRONS ("LOAD") 

ENVIRONS returns a null string because 'LOAD" 
is not in the table; however, "load" is in the table. 

Example: When DOS loads initially, it sets a parameter called 
"COMSPEC" that tells DOS where to locate the 
COMMAND.COM file, and it sets up a null path. 
To observe the contents of the environment table at 
start-up time, enter the following from BASIC: 

PRINT ENVIRONS (1) 
You now see printed on the screen: 

PATH= 
If you enter: 

PRINT ENVIRONS (2) 
you see displayed: 

COMSPEC = A:\COMMAND.COM 

Note: If you booted from a fixed disk, the 
previous example displays C: instead of A: for 
the drive specification. 
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ENVIRONS 
Function 

If you enter: 



PRINT ENVIRONS ("COMSPEC") 
the computer's response is: 

A:\C0MMAND.C0M 

The following program saves BASIC'S environment 
table in an array so that it can be modified for a child 
process. After the child process is completed, the 
environment is restored. 

10 DIM TABLE$(10) 'assume no more than 10 parms 
20 PARMS = 1 'initial number of parameters 

30 WHILE LEN(ENVIRON$(PARMS)) > 
40 TABLE$(PARMS) = ENVIRON$(PARMS) 
50 PARMS = PARMS+1 
60 WEND 

70 PARMS = PARMS - I 'adjust to correct number 
80 'now store new environment 
90 ENVIRON "DATAIN = C:\DATAIN\INP.FIL" 
100 ENVIRON "SORT. DAT = S0RT.DAT<" + 
ENVIRONS ("DATAIN") +">LPT1:" 



1000 SHELL ENVIRON$("SORT.DAT") "data is sorted 

1010 FOR I = 1 TO PARMS 

1020 ENVIRON TABLE$(I) 'restore parameters 

1030 NEXT I 



Note: See also "ENVIRON Statement" and 
"SHELL Command." Also "SET Command" in 
Disk Operating System Reference and "EXEC 
Function Call" in Disk Operating System 
Technical Reference. 
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EOF 
Function 



Purpose: Indicates an end-of-file condition. 
Versions: Cassette Disk Advanced Compiler 

Format: v = EOF(filenum) 
Remarks: 

filenum is the number specified on the OPEN 
statement. 

The EOF function is useful for avoiding an Input past 
end error. EOF returns -1 (true) if end of file has 
been reached on the specified file. A (zero) is 
returned if end of file has not been reached. 

EOF is significant only for a file opened for 
sequential input from disk or cassette, or for a 
communications file. A -1 for a communications file 
means the buffer is empty. 
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EOF 

Function 

Example: This example reads information from the sequential 
file named "DATA". Values are read into the array 
M until end of file is reached. 

10 OPEN "DATA" FOR INPUT AS #1 

20 C=0 

30 IF E0F(1) THEN END 

40 INPUT #1,M(C) 

50 C=C+1: GOTO 30 

EOF(0) returns the end-of-file condition on 
standard input devices used with redirection of I/O. 
(For BASIC 2.0 and later releases.) 



88 



ERASE 

Statement 



Purpose: Eliminates arrays from a program. 
Versions: Cassette Disk Advanced Compiler 



Cassette 

*** 



Disk 

*** 



Advanced 



Format: ERASE arrayname[,arrayname\ . . . 

Remarks: 

arrayname is the name of the array you want to 
erase. 

You may want to use the ERASE statement if you 
are running short of storage space while running a 
program. After arrays are erased, the space in 
memory allocated for the arrays can be used for 
other purposes. 

ERASE can also be used when you want to 
redimension arrays in your program. If you try to 
redimension an array without first erasing it, a 
Duplicate definition error occurs. 

The CLEAR command erases all variables from the 
work area. 
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ERASE 

Statement 

Example: This example uses the FRE function to show how 

ERASE can be used to free memory. The array BIG 
used up about 40K bytes of memory (62808-21980) 
when it was dimensioned as BIG(1000). After it 
was erased, it could be redimensioned to 
BIG (10, 10), and it took up only a little more than 
500 bytes (62808-6228). 

The actual values returned by the FRE function may 
be different on your computer. 

10 START=FRE("") 
20 DIM BIG(100,100) 
30 MIDDLE=FRE("") 
40 ERASE BIG 
50 DIM BIG(10,10) 
60 FINAL=FRE("") 
70 PRINT START, MIDDLE, FINAL 
RUN 
62808 21980 62289 
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ERDEV and ERDEV$ 

Variables 



Purpose: Read-only variables. Hold the INTerrupt 24 error 
code of a device error, and the name of the device 
generating the error. 

Not valid for BASIC releases earlier than 3.0. 



Versions: Cassette 



Disk Advanced Compiler 



Format: v = ERDEV 

v$ = ERDEV$ 

Remarks: ERDEV is a read-only variable. When an error in 
DOS is detected, ERDEV holds the INTerrupt 24 
error code in the lower 8 bits, and the upper 8 bits 
contain bits 13, 14, and 15 of the attribute word of 
the device header block. 

ERDEV$ is a read-only variable. If the error was on 
a character device, ERDEV$ contains the 8-byte 
character device name. If the error was not on a 
character device, ERDEV$ contains the two- 
character block device name (A:, B:, C:, etc.). 
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ERDEV and ERDEV$ 

Variables 

Example: Open the B drive door and enter the following: 

FILES "B:" 

and BASIC returns: 

Disk not ready 

Then enter: 

PRINT ERDEV, ERDEV$ 

and BASIC returns: 
2 B: 

Note: If you refer to Disk Operating System 
Technical Reference manual under the INT24 
error code listing, you can see that error 2 is 
Drive not ready. The high-order 8 bits (the word 
attribute bits) are all zeros. As explained in the 
DOS Technical Reference section called 
"Attribute Field" under "Installable Device 
Drivers," bits 13, 14, and 15 set to zero means 
that B: is a block device, IOCTL is not 
supported, and the device is in IBM format. 

See also "IOCTL Statement" and "IOCTL$ 
Function." 
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ERDEV and ERDEV$ 

Variables 

This example simulates a printer error. 

10 CLS 

20 ON ERROR GOTO 50 

30 LPRINT"The printer is rezdy" 

40 PRINT"The printer is re^dy" 

50 END 

60 V$=HEX$(ERDEV) 

70 PRINT "ERDEV = ";V$ 

80 D$=ERDEV$ 

90 PRINT "ERDEV$ - ";D$ 

100 RESUME NEXT 

If you run this example with the printer turned off, 
the computer displays: 

ERDEV = 8009 
ERDEV$ = LPT1 

The lower 8 bits (bits 0-7) of the binary equivalent 
equal 9, which is the INT24 error code for Printer 
out of paper. The meaning of bits 13, 14, and 15 of 
the value returned by ERDEV is explained in the 
section "Attribute Field" of Disk Operating System 
Technical Reference under "Installable Device 
Drivers." 
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ERR and ERL 

Variables 



Purpose: Return the error code and line number associated 
with an error. 



Versions: Cassette Disk 



Advanced Compiler 



Format: v = ERR 

v = ERL 

Remarks: The variable ERR contains the error code for the last 
error, and the variable ERL contains the line number 
of the line in which the error was detected. The 
ERR and ERL variables are usually used in 
IF-THEN statements to direct program flow in the 
error-handling routine. See "ON ERROR 
Statement." 

If you do test ERL in an IF-THEN statement, be 
sure to put the line number on the right side of the 
relational operator, like this: 

IF ERL = line number THEN ... 

The number must be on the right side of the 
operator to be renumbered by RENUM. 

If the statement that caused the error was a direct 
mode statement, ERL contains 65535. You do not 
want this number changed during a RENUM, so to 
test whether an error occurred in a direct mode 
statement use the form: 

IF 65535 = ERL THEN ... 
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ERR and ERL 

Variables 

ERR and ERL can be set using the ERROR 
statement (see next entry). 

BASIC error codes are listed in Appendix A, "Error 

Messages." 

Example: This example tests to see if the drive door is open 
when the program needs to open a file. 

10 ON ERROR GOTO 100 

20 OPEN "DATA" FOR INPUT AS #1 

30 END 



100 IF ERR=71 THEN LOCATE 23,1: 

PRINT "DISK IS NOT READY" : RESUME 
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ERROR 

Statement 



Purpose: 



Versions: 



Simulates the occurrence of a BASIC error; or allows 
you to define your own error codes. 



Cassette 
*** 



Disk 

*** 



Advanced 

*** 



Compiler 

*** 



Format: ERROR n 



Remarks: 



n must be an integer expression between and 

255. 

If the value of n is the same as an error code used by 
BASIC (see Appendix A, "Error Messages"), the 
ERROR statement simulates the occurrence of that 
error. If an error-handling routine has been defined 
by the ON ERROR statement, the error routine is 
entered. Otherwise, the error message corresponding 
to the code is displayed, and execution halts. See the 
first example below. 

To define your own error code, use a value that is 
different from any used by BASIC. (We suggest you 
use the highest available values; for example, values 
greater than 200.) This new error code can then be 
tested in an error handling routine, just like any other 
error. See the second example below. 

If you define your own code in this way, and you 
don't handle it in an error handling routine, BASIC 
displays the message Unprintable error, and execution 
halts. 



96 



ERROR 

Statement 

Example: The first example simulates a String too long error. 

10 T = 15 

20 ERROR T 

RUN 

String too long in line 20 

The next example is a part of a game program that 
allows you to make bets. By using an error code of 
210, which BASIC doesn't use, the program traps 
the error if you exceed the house limit. 



100 ON ERROR GOTO 1! 

110 INPUT "WHAT IS YOUR BET";[ 

120 IF B > 5000 THEN ERROR 210 



1000 IF ERR = 210 THEN PRINT 

"HOUSE LIMIT IS $5000" 
1010 IF ERL - 120 THEN RESUME 110 
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EXP 

Function 

Purpose: Calculates the exponential function. 



Versions: 



Cassette 
*** 



Disk 

*** 



Advanced 

*** 



Compiler 

*** 



Format: v = EXP(jc) 

Remarks: x can be any numeric expression. 

This function returns the mathematical number e 
raised to the x power, e is the base for natural 
logarithms. An overflow occurs if jc is greater than 
88.02969. 

In BASIC 2.0 and later releases, you can have this 
calculation performed in double-precision by 
specifying /D in the BASIC command line when 
BASIC is initially loaded. See "Options in the 
BASIC Command" in the BASIC Handbook. 

Example: This example calculates e raised to the (2-1) power, 
which is simply e. 

10 X = 2 

20 PRINT EXP(X-l) 
RUN 
2.718282 



98 



FIELD 

Statement 

Purpose: Allocates space for variables in a random file buffer. 
Versions: Cassette Disk Advanced Compiler 

Format: FIELD [#]filenum, width AS stringvar [,width AS 
stringvar]... 



Remarks: 



filenum is the number under which the file was 

opened. 

width is a numeric expression specifying the 

number of character positions to be 
allocated to stringvar. 

stringvar is a string variable that is used for 
random file access. 

A FIELD statement defines variables used to get 
data out of a random buffer after a GET or to enter 
data into the buffer for a PUT. 

The statement: 

FIELD 1, 20 AS N$, 10 AS ID$, 40 AS ADD$ 

allocates the first 20 positions (bytes) in the random 
file buffer to the string variable N$, the next 10 
positions to ID$, and the next 40 positions to ADD$. 
FIELD does not actually place any data into the 
random file buffer. This is done by the LSET and 
RSET statements. See "LSET and RSET 
Statements." 
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FIELD 

Statement 



FIELD does not "remove" data from the file either. 
Information is read from the file into the random file 
buffer with the GET (file) statement. Information is 
read from the buffer by simply referring to the 
variables defined in the FIELD statement. 

The total number of bytes allocated in a FIELD 
statement must not exceed the record length 
specified when the file was opened. Otherwise, a 
Field overflow error occurs. 

Any number of FIELD statements can be executed 
for the same file number, and all FIELD statements 
that have been executed are in effect at the same 
time. Each new FIELD statement redefines the 
buffer from the first character position, so this has 
the effect of having multiple field definitions for the 
same data. 

Note: Be careful about using a fielded variable 
name in an input or assignment statement. Once 
a variable name is defined in a FIELD statement, 
it points to the correct place in the random file 
buffer. If a subsequent input statement or LET 
statement with that variable name on the left side 
of the equal sign is executed, the variable is 
moved to string space and is no longer in the file 
buffer. 

See Appendix A, "BASIC Disk Input and Output," 
in the BASIC Handbook for a complete explanation 
of how to use random files. 
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Example: 



FIELD 
Statement 



This example opens a file named "CUST" as a 
random file. The variable CUSTNO$ is assigned to 
the first two positions in each record; CUSTNAME$ 
is assigned to the next 30 positions; and ADDR$ is 
assigned to the next 35 positions. 

Lines 30 through 50 put information into the buffer, 
and the PUT statement in line 60 writes the buffer to 
the file. Line 70 reads back that same record, and 
line 90 displays the three fields. Note in line 80 that 
it is permissible to use a variable name that was 
defined in a FIELD statement on the right side of an 
assignment statement. 



10 


OPEN "A:CUST" AS #1 


20 


FIELD 1, 2 AS CUSTN0$, 30 AS CUSTNAME$, 




35 AS ADDR$ 


30 


LSET CUSTNAME$= "0 'NEIL INC" 


40 


LSET ADDR$= "50 SE 12TH ST, NY, NY" 


50 


LSET CUSTNO$=MKI$(7850) 


60 


PUT 1,1 


70 


GET 1,1 


80 


CNUM%= CVI(CUSTN0$): N$ = CUSTNAME$ 


90 


PRINT CNUM%, N$, ADDR$ 



The program below shows a way to create a random 
file buffer with multiple FIELD statements in a line. 

10 OPEN "F00" AS #1 

20 FIELD 1, 100 AS A$, 200 AS B$ 

30 FIELD 1, 300 AS DUMMY$, 40 AS C$ 

Note that in line 30 DUMMY$ moves the pointer 
into the file buffer so that you do not lose the 
information in line 20. 
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FILES 
Command 



Purpose: Displays the names of files residing on the current 
directory of a disk. The FILES command in BASIC 
is similar to the DIR command in DOS. 



Versions: Cassette Disk 

*** 

Format: FILES [filespec] 
Remarks: 



Advanced Compiler 



filespec is a string expression for the file 

specification. It must conform to the 
rules outlined under "Naming Files" in 
Chapter 3 of the BASIC Handbook; 
otherwise, a Bad file name error occurs. 
If filespec is omitted, all the files on the 
current directory of the DOS default 
drive are listed. 

All files matching the filename are displayed. The 
filename can contain question marks (?). A question 
mark matches any character in the name or 
extension. An asterisk (*) as the first character of 
the name or extension matches any name or any 
extension. 

If a drive is specified as part of filespec, files that 
match the specified filename on the current directory 
of that drive are listed. Otherwise, the DOS default 
drive is used. 
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FILES 
Command 

Example: This command displays all files on the current 
directory of the DOS default drive. 

FILES 

This displays all files with an extension of .BAS on 
the current directory of the DOS default drive. 

FILES "*.BAS" 

This displays all files on drive B. 

FILES "B:*.*" 

This lists each file on the current directory of the 
DOS default drive that has a filename beginning with 
TEST followed by up to two other characters, and an 
extension of .BAS. 

FILES "TEST??. BAS" 

Another way to list all the files on the current 
directory of drive B is: (For BASIC 2.0 and later 
releases.) 

FILES "R-" 

In addition to listing all the files on the current 
directory of the drive, BASIC displays the current 
directory name and the number of bytes free. 

When using tree-structured directories, remember 
that each subdirectory contains two special entries. 
They are listed when you use the FILES command to 
list a subdirectory. The first contains a single period 
instead of a filename. It identifies this "file" as a 
subdirectory. The second entry contains two periods 
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FILES 

Command 



instead of a filename. It is used to locate the higher 
level directory that defines this subdirectory. (For 
BASIC 2.0 and later releases.) 

This example lists all files in the current subdirectory 
called LEVEL 1 on drive A. Note that the directory 
is empty. 

FILES "A:\LEVEL1" 

<DIR> .. <DIR> 

32824 Bytes free 

The FILES command can also be used to list files in 
other directories. The example below lists all files in 
the subdirectory LVL1. The backslash must be used 
after the directory name. 

FILES "LVL1\" 

This example lists all files in the directory LVL2 
with an extension of .BAS. 

FILES "LVL2\*.BAS" 
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FIX 

Function 



Purpose: Truncates x to an integer. 



Versions: Cassette Disk 



Advanced Compiler 



Format: v = FIX(;t) 

Remarks: x can be any numeric expression. 

FIX strips all digits to the right of the decimal point 
and returns the value of the digits to the left of the 
decimal point. 

The difference between FIX and INT is that FIX 
does not return the next lower number when x is 
negative. 

See the "INT" and "CINT" functions, which also 
return integers. 

Example: Note in the examples how FIX does not round the 
decimal part when it converts to an integer. 

PRINT FIX(45.67) 
45 

PRINT FIXC-2.89) 
-2 
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FOR and NEXT 

Statements 



Purpose: 


Performs a series of instructions in a loop a given 
number of times. 


Versions: 


Cassette Disk Advanced Compiler 


Format: 


FOR variable =x TO y [STEP z] 



Remarks: 



NEXT [variable [,variable]. 



variable is an integer or single-precision variable 
to be used as a counter. 

x is a numeric expression that is the initial 

value of the counter. 



y 



is a numeric expression that is the final 
value of the counter. 



z is a numeric expression to be used as an 

increment. 

The program lines following the FOR statement are 
executed until the NEXT statement is encountered. 
Then the counter is incremented by the amount 
specified by the STEP value (z). If you do not 
specify a value for z, the increment is assumed to be 
1 . A check is performed to see if the value of the 
counter is now greater than the final value y. If it is 
not greater, BASIC branches back to the statement 
after the FOR statement and the process is repeated. 
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FOR and NEXT 

Statements 

If it is greater, execution continues with the 
statement following the NEXT statement. This is a 
FOR-NEXT loop. 

If the value of z is negative, the test is reversed. The 
counter is decremented each time through the loop, 
and the loop is executed until the counter is less than 
the final value. 

The body of the loop is skipped if x is already greater 
than y when the STEP value is positive, or x is less 
than y when the STEP value is negative. If z is zero, 
an infinite loop is created unless you provide some 
way to set the counter greater than the final value. 

Program performance will be improved if you use 
integer counters whenever possible. 

Nested Loops 

FOR-NEXT loops can be nested; that is, one 
FOR-NEXT loop can be placed inside another 
FOR-NEXT loop. When loops are nested, each 
loop must have a unique variable name as its counter. 
The NEXT statement for the inside loop must appear 
before that for the outside loop. If nested loops have 
the same end point, a single NEXT statement can be 
used for all of them. 



107 



FOR and NEXT 

Statements 

A NEXT statement of the form: 

NEXT varl , var2, var3 ... 

is equivalent to the sequence of statements: 

NEXT varl 
NEXT var2 
NEXT var3 



The variable(s) in the NEXT statement can be 
omitted, in which case the NEXT statement matches 
the most recent FOR statement. It is a good idea 
always to include the variables to avoid confusion; 
but it can be necessary if you do any branching out 
of nested loops. However, using variable names on 
the NEXT statements causes your program to 
execute somewhat slower. 

Active loops should be exited by setting the loop 
counter out of range or setting a conditional 
statement with the loop causing the loop to 
terminate, so that every iteration of the FOR 
statement in the loop has a corresponding NEXT. 

If a NEXT statement is encountered before its 
corresponding FOR statement, a NEXT without FOR 

error occurs. 
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FOR and NEXT 
Statements 

Example: The first example shows a FOR-NEXT loop with a 
STEP value of 2. 



10 


J = 10: K= 


:30 






20 


FOR 1=1 


TO J 


STEP 


2 


30 

40 


PRINT I: 
K=K+10 


\ 






50 
60 


PRINT K 
NEXT 








RUh 


I 








1 


40 








3 


50 








5 


60 








7 


70 








9 


80 









In the following example, the loop does not execute 
because the initial value of the loop is more than the 
final value: 

10 J = 

?0 FOR 1=1 TO J 

30 PRINT I 

40 NEXT I 

RUN 

The next program results in a NEXT without FOR 
error. There can be only one NEXT statement for 
every FOR statement. (This is different from other 
versions of BASIC that allow a different physical 
NEXT statement when jumping out of a loop.) 

10 FOR 1=1 TO 5 
20 IF 1=2 GOTO 50 
30 NEXT 
40 GOTO 60 
50 NEXT 
60 END 
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FOR and NEXT 

Statements 



In the last example, the loop executes 10 times. 
The final value for the loop variable is always set 
before the initial value is set. (This is different from 
some other versions of BASIC, which set the initial 
value of the counter before setting the final value. In 
another BASIC the loop in this example might 
execute six times.) 

10 1=5 

20 FOR 1=1 TO 1+5 
30 PRINT I; 
40 NEXT 
RUN 
1 2 3 4 5 6 7 8 9 10 
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Purpose: 



FRE 

Function 



Returns the number of bytes within BASIC'S data 
space that are not being used. This number does not 
include the size of the reserved portion of the 
interpreter work area. 



Versions: Cassette Disk Advanced Compiler 

Format: v = FRE(x) 

v = FREW) 

Remarks: x and x$ are dummy arguments. 

Since strings in BASIC can have variable lengths 
(each time you do an assignment to a string its length 
can change), strings are manipulated dynamically. 
For this reason, string space can become fragmented, 
causing a decrease in program performance. 

You can improve the performance of programs that 
execute many string functions by using the MID$ 
statement to access substrings imbedded within one 
large string. This prevents fragmentation of string 
space. See "MID$ Statement" for an example. 

FRE with any string value causes a housecleaning 
before returning the number of free bytes. During 
housecleaning, BASIC collects all its useful data and 
frees up unused areas of memory once used for 
strings. The data is compressed so you can continue 
until you really run out of space. 
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FRE 

Function 

BASIC also automatically does a housecleaning 
when it is running out of usable work area. Be 
patient; housecleaning can take a while. 

Note: Ctrl-Break cannot be used during 
housecleaning. 

Example: The actual value returned by FRE on your computer 
can differ from this example. 

PRINT FRE(0) 
14542 
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GET 

Statement (Files) 



Purpose: Reads a record from a random file into a random 
buffer. 

Versions: Cassette Disk Advanced Compiler 



Format: GET [#]filenum[, number] 

Remarks: 

filenum is the number under which the file was 
opened. 

number is the number of the recorcbto be read, in 
the range 1 to 16 megabytes. If number is 
omitted, the next record (after the last 
GET) is read into the buffer. 

After a GET statement, INPUT #, LINE INPUT #, 
or references to variables defined in the FIELD 
statement can be used to read characters from the 
random file buffer. See Appendix A, "BASIC Disk 
Input and Output," in the BASIC Handbook for 
more information on using GET. 

Because BASIC and DOS block as many records as 
possible in 512-byte sectors, the GET statement 
does not necessarily perform a physical read from the 
disk. 

GET can also be used for communications files. In 
this case number is the number of bytes to read from 
the communications buffer. This number cannot 

exceed the value set by the LEN option on the 
OPEN "COM... statement. 



113 



GET 

Statement (Files) 

Example: This example opens the file "CUST" for random 
access, with fields defined in line 20. The GET 
statement on line 30 reads a record into the file 
buffer. Line 40 displays the information from the 
record that was read. 

10 OPEN "A:CUST" AS #1 

20 FIELD 1, 30 AS CUSTNAME$, 30 AS ADDR$, 

35 AS CITY$ 
30 GET 1 
40 PRINT CUSTNAME$, ADDR$, CITY$ 
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GET 

Statement (Graphics) 



Purpose: Reads points from an area of the screen. 
Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



Graphics mode only. 

GET (xl,yl)-(x2,y2),arrayname 



(xl,yl), (x2,y2) 

are coordinates in either absolute or 
relative form. Refer to "Specifying 
Coordinates" under "Graphics 
Modes" in Chapter 3 of the BASIC 
Handbook for more information on 
coordinates. 

arrayname is the name of the array you want to 
hold the information. 

GET reads the attributes of the points within the 
specified rectangle into the array. The specified 
rectangle has points (xl,yl) and (x2,y2) as opposite 
corners. (This is the same as the rectangle drawn by 
the LINE statement using the B option.) 

GET and PUT can be used for high-speed object 

motion in graphics mode. You might think of GET 

and PUT as "bit pump" operations that move bits 
onto (PUT) and off (GET) the screen. Remember 

that PUT and GET are also used for random access 

files, but the syntax of these statements is different. 
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GET 

Statement (Graphics) 



The array is used simply as a place to hold the image 
and must be numeric; it can be any precision, 
however. The required size of the array, in bytes, is: 

4+INT((x*bitsperpixel+7)/8)*y 

where x and y are the lengths of the horizontal and 
vertical sides of the rectangle, respectively. The 
value of bitsperpixel is 2 in medium resolution, and 1 
in high resolution. 

For example, suppose you want to use the GET 
statement to get a 10 by 12 image in medium 
resolution. The number of bytes required is 
4+INT((10*2+7)/8)*12, or 40 bytes. The bytes 
per element of an array are: 



2 for integer string 

4 for single-precision string 

8 for double-precision string 



Therefore, you could use an integer array with at 
least 20 elements. 

The information from the screen is stored in the 
array as follows: 

1 . 2 bytes giving the x dimension in bits 

2. 2 bytes giving the y dimension in bits 

3 . the data itself 

It is possible to examine the jc and y dimensions and 
even the data itself if an integer array is used. The jc 
dimension is in element of the array, and the y 
dimension is in element 1 . 

Keep in mind that integers are stored low byte first, 
then high byte; but the data is actually transferred 
high byte first, then low byte. 
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GET 

Statement (Graphics) 

The data for each row of points in the rectangle is 
left-justified on a byte boundary, so if less than a 
multiple of 8 bits is stored, the rest of the byte is 
filled with zeros. 

PUT and GET work significantly faster in medium 
resolution when xl MOD 4 is equal to zero, and in 
high resolution when xl MOD 8 is equal to zero. 
This is a special case where the rectangle boundaries 
fall on the byte boundaries. 

Example: See "PUT Statement (Graphics)" for an example. 
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GOSUB and RETURN 

Statements 



Purpose: Branches to and returns from a subroutine. 
Versions: Cassette Disk Advanced Compiler 



Format: GOSUB line 



Remarks: 



RETURN 



line is the line number of the first line of the 
subroutine. 

A subroutine can be called any number of times in a ( 
program, and a subroutine can be called from within v 
another subroutine. Such nesting of subroutines is 
limited only by available memory. 

The RETURN statement causes BASIC to branch 
back to the statement following the most recent 
GOSUB statement. A subroutine can contain more 
than one RETURN statement, so you can return 
from different points in the subroutine. Subroutines 
can appear anywhere in the program. 

To prevent your program from accidentally entering 
a subroutine, you can put a STOP, END, or GOTO 
statement before the subroutine to direct program 
control around it. 

Use ON-GOSUB to branch to different subroutines ( 
based on the result of an expression. 
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GOSUB and RETURN 

Statements 

Example: This example shows how a subroutine works. The 

GOSUB in line 10 calls the subroutine in line 40. So 
the program branches to line 40 and starts executing 
statements there until it sees the RETURN statement 
in line 70. At that point the program goes back to 
the statement after the subroutine call; that is, it 
returns to line 20. The END statement in line 30 
prevents the subroutine from being performed a 
second time. 



10 


GOSUB 40 


20 


PRINT 


"BACK FROM SUBROUTINE" 


30 


END 




40 


PRINT 


"SUBROUTINE"; 


50 


PRINT 


11 IN"; 


60 


PRINT 


" PROGRESS" 


70 


RETURN 




RUN 




SUBROUTINE 


; IN PROGRESS 


BACK FROM 


SUBROUTINE 
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GOTO 
Statement 



Purpose: Branches unconditionally out of the normal program 
sequence to a specified line number. 



Versions: 



Cassette 

*** 



Disk 



Advanced 

*** 



Compiler 

*** 



Format: GOTO line 



Remarks: 



line is the line number of a line in the program. 

If line is the line number of an executable statement, 
that statement and those following are executed. If 
line refers to a nonexecutable statement (such as 
REM or DATA) , the program continues at the first 
executable statement encountered after line. 

The GOTO statement can be used in direct mode to 
reenter a program at a desired point. This can be 
useful in debugging. 

Use ON-GOTO to branch to different lines based 
on the result of an expression. 
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GOTO 
Statement 

Example: In this example, the GOTO statement in line 60 puts 
the program into an infinite loop, which is stopped 
when the program runs out of data in the DATA 
statement. (Notice how branching to the DATA 
statement does not add additional values to the 
internal data table.) 

10 DATA 5,7,12 

20 READ R 

30 PRINT "R = ";R, 

40 A = 3.14*Ra2 

50 PRINT "AREA = ";A 

60 GOTO 10 

RUN 

R = 5 AREA = 78.5 

R = 7 AREA = 153.86 

R = 12 AREA = 452.16 

OUT OF DATA IN 20 
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HEX$ 

Function 



Purpose: Returns a string that represents the hexadecimal 
value of the decimal argument. 



Versions: Cassette Disk 



Advanced Compiler 



Format: 
Remarks: 



v$ = HEX$(rc) 



n is a numeric expression in the range -32768 to 

65535. 

If n is negative, the twos complement form is used. 
That is, HEX$(-«) is the same as HEX$(65536-«). 

See "OCT$ Function" for octal conversion. 

Example: The following example uses the HEX$ function to 
figure the hexadecimal representation for the two 
decimal values that are entered. 

10 INPUT X 

20 A$ = HEX$(X) 

30 PRINT X " DECIMAL IS ";A$ " HEXADECIMAL" 

RUN 
? 32 

32 DECIMAL IS 20 HEXADECIMAL 
RUN 
? 1023 

1023 DECIMAL IS 3FF HEXADECIMAL 
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IF 

Statement 



Purpose: 



Versions: 



Makes a decision regarding program flow based on 
the result of an expression. 



Cassette 
*** 



Disk 



Advanced 



Compiler 



Format: IF expression [JTHEN clause [ELSE clause] 
IF expression [JGOTO line [[,]ELSE clause] 
Remarks: 



expression 
clause 



line 



can be any numeric expression. 

can be a BASIC statement or a 
sequence of statements (separated by 
colons) ; or it can be simply the 
number of a line to branch to. 

is the line number of a line existing in 
the program. 



If the expression is true (not zero), the THEN or 
GOTO clause is executed. THEN is followed by 
either a line number for branching or one or more 
statements to be executed. GOTO is always 
followed by a line number. 

If the result of expression is false (zero), the THEN 
or GOTO clause is ignored and the ELSE clause, if 
present, is executed. Execution then continues with 
the next numbered line containing an executable 
statement. 



123 



IF 

Statement 



If you enter an IF-THEN statement in direct mode, 
and it directs control to a line number, an Undefined 
line number error results unless you previously 
entered a line with the specified line number. 

Note: When using IF to test equality for a value 
that is the result of a single- or double-precision 
computation, remember that the internal 
representation of the value may not be exact. 
(This is because single- and double-precision 
values are stored internally in floating point 
binary format.) Therefore, the test should be 
against the range over which the accuracy of the 
value can vary. For example, to test a computed 
variable A against the value 1.0, use: 

IF ABS (A-1.0)<1.0E-6 THEN ... 

This test returns a true result if the value of A is 
1.0 with a relative error of less than 1.0E-6. 

Also note that IF-THEN-ELSE is just one statement. 
Once an IF statement occurs on a line, everything 
else on that line is part of the IF statement. Because 
IF-THEN-ELSE is all one statement, the ELSE 
clause cannot be a separate program line. For 
example: 

10 IF A=B THEN X=4 
20 ELSE P=Q 

is invalid. Instead, it should be: 

10 IF A=B THEN X=4 ELSE P=Q 

Nesting of IF Statements: IF-THEN-ELSE 

statements can be nested. Nesting is limited only by 
the length of the line. For example, 
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IF 

Statement 



IF X>Y THEN PRINT "GREATER" ELSE IF Y>X 

THEN PRINT "LESS THAN" ELSE PRINT "EQUAL" 

is a valid statement. If the statement does not 
contain the same number of ELSE and THEN 
clauses, each ELSE is matched with the closest 
unmatched THEN. For example: 

IF A=B THEN IF B=C THEN PRINT "A=C" 
ELSE PRINT "A<>C" 

will not print "A<>C" when A<>B. 

Example: This statement gets record I if I is not zero: 

100 IF I THEN GET #1,1 

In the next example, if I is between 10 and 20, DB 
is calculated and execution branches to line 300. If I 
is not in this range, the message Out of range is 
printed. Note the use of two statements in the 
THEN clause. 

100 IF (I>10) AND (I<20) THEN 
DB=1982-I: GOTO 300 
ELSE PRINT "OUT OF RANGE" 



125 



IF 

Statement 



In the next example, in line 20 everything after the 
THEN is part of the clause. This means that the 
NEXT is not executed unless N=I. When line 
20 executes, N does not equal I so the IF evaluation 
is false. Therefore, the NEXT is not performed and 
the program falls through to line 30. The NEXT 
must be coded on a separate line if you want the 
program to loop until N=I. 

10 N=15 

20 FOR 1=1 TO 20: IF N=I THEN 40:NEXT 

30 PRINT "N <> I":END 

40 PRINT "N = I" 

RUN 

N <> I 
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INKEY$ 

Variable 



Purpose: Reads a character from the keyboard. 
Versions: Cassette Disk Advanced Compiler 



Format: v$ = INKEY$ 

Remarks: INKEY$ reads only a single character, even if 

several characters are waiting in the keyboard buffer. 
The returned value is a zero-, one-, or two-character 
string. 

• A null string (length zero) indicates that no 
character is pending at the keyboard. 

• A one-character string contains the actual 
character read from the keyboard. 

• A two-character string indicates a special 
extended code. The first character is hex 00. For 
a complete list of these codes, see Appendix D, 
"ASCII Character Codes." 

You must assign the result of INKEY$ to a string 
variable before using the character with any BASIC 
statement or function. 

While INKEY$ is being used, no characters are 
displayed on the screen and all characters are passed 
through to the program except for: 

• Ctrl-Break, which stops the program 

• Ctrl-Num Lock, which sends the system into a 
pause state 

• Alt-Ctrl-Del, which does a System Reset 

• PrtSc, which prints the screen 
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INKEY$ 

Variable 



If you press Enter in response to INKEY$, the 
carriage return character passes through to the 
program. 

Example: The following section of a program stops execution 
until any key is pressed: 

100 PRINT "Press any key to continue" 
110 A$=INKEY$: IF A$="" THEN 110 

The next example shows program lines that could be 
used to test a two-character code being returned: 

100 KB$=INKEY$ 

110 IF LEN(KB$)=2 THEN KB$=RIGHT$(KB$ ,1 ) 
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INP 

Function 



Purpose: Returns the byte read from port n. 



Versions: Cassette Disk 



Advanced Compiler 



Format: v = INP(h) 

Remarks: n must be in the range to 65535. 

INP is the complementary function to the OUT 
statement. See "OUT Statement." 

INP performs the same function as the IN instruction 
in assembly language. See also the IBM Personal 
Computer Technical Reference manual for a 
description of valid port numbers (I/O addresses). 

Example: This instruction reads a byte from port 255 and 
assigns it to the variable A. 

100 A=INP(255) 
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INPUT 

Statement 



Purpose: Receives input from the keyboard during program 
execution. 

Versions: Cassette Disk Advanced Compiler 

Format: INPUT[;][ "prompt";] variable[,variable\... 
Remarks: 

"prompt" is a string constant that prompts for the 
desired input. 

variable is the name of the numeric or string 

variable or array element that receives 
the input. 

When the program sees an INPUT statement, it 
pauses and displays a question mark on the screen to 
indicate that it is waiting for data. If a "prompt" is 
included, the string is displayed. If "prompt'" is 
followed by the semicolon (;), a question mark will 
follow the displayed string; if "prompt " is followed 
by a comma, the question mark is not displayed. 

You can use a comma instead of a semicolon after 
the prompt string to suppress the question mark. For 
example, the statement INPUT "ENTER 
BIRTHDATE",B$ prints the prompt without the 
question mark. 

After the prompt or question mark is displayed, you 
can enter the required data from the keyboard. The 
data you enter is assigned to the variables given in the 
variable list. The data items you supply must be 
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INPUT 

Statement 

separated by commas, and the number of data items 
must be the same as the number of variables in the 
list. 

The type of data item that you enter must agree with 
the type specified by the variable name. (Strings 
entered in response to an INPUT statement need not 
be surrounded by quotation marks.) 

If you respond to INPUT with too many or too few 
items, or with the wrong type of value (letters 
instead of numbers, etc.), BASIC displays the 
message ?Redo from start. If a single variable is 
requested, you can simply press Enter to indicate the 
default values of for numeric input or null for 
string input. However, if more than one variable is 
requested, pressing Enter causes the ?Redo from start 
message to be printed because too few items were 
entered. BASIC does not assign any of the input 
values to variables until you give an acceptable 
response. 

In Disk BASIC and Advanced BASIC, if INPUT is 

immediately followed by a semicolon, then pressing 
Enter to input data does not produce a carriage 
return/line feed sequence on the screen. This means 
that the cursor remains on the same line as your 
response. 

Example: In this example, the question mark displayed by the 
computer is a prompt to tell you it wants you to enter 
something. Suppose you enter a 5. 

10 INPUT X 

20 PRINT X "SQUARED IS" Xa2 

30 END 
RUN 
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INPUT 

Statement 

The program continues: 



? 5 
5 SQUARED IS 25 

For this second example, a prompt was included in 
line 20, so this time the computer prompts with 
"WHAT IS THE RADIUS?" 

10 PI=3.14 

20 INPUT "WHAT IS THE RADIUS" ;R 

30 A=PI*Ra2 

40 PRINT "THE AREA OF THE CIRCLE IS " ;A 

50 END 

RUN 

WHAT IS THE RADIUS? 

Suppose you respond with 7.4. The program 
continues: 



WHAT IS THE RADIUS? 7.4 

THE AREA OF THE CIRCLE IS 171.9464 
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INPUT # 
Statement 



Purpose: Reads data items from a sequential device or file and 
assigns them to program variables. 



Versions: Cassette Disk 



Advanced Compiler 



Format: INPUT ttfilenum, variable [, variable]... 
Remarks: 

filenum is the number used when the file was 

opened for input. 

variable is the name of a variable that will have 
an item in the file assigned to it. It can 
be a string or numeric variable, or an 
array element. 

The sequential file can reside on disk or on cassette; 
it can be a sequential data stream from a 
communications adapter; or it can be the keyboard 
(KYBD:). 

The type of data in the file must match the type 
specified by the variable name. Unlike INPUT, no 
question mark is displayed with INPUT #. 

The data items in the file must appear just as they 
would if the data were being typed in response to an 
INPUT statement. With numeric values, the leading 
spaces, carriage returns, and line feeds are ignored. 
The first character encountered that is not a space, 
carriage return, or line feed is assumed to be the start 
of the number. The number ends with a space, 
carriage return, line feed, or comma. 
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INPUT # 
Statement 

If BASIC is scanning the data for a string item, the 
leading spaces, carriage returns, and line feeds are 
also ignored. The first character encountered that is 
not a space, carriage return, or line feed is assumed 
to be the start of the string item. If this first 
character is a quotation mark ("), the string item 
consists of all characters read between the first 
quotation mark and the second. Thus, a quoted 
string cannot contain a quotation mark as a 
character. If the first character of the string is not a 
quotation mark, the string is an unquoted string. It 
ends after a comma, carriage return, or line feed - or 
after 255 characters have been read. If end of file is 
reached when a numeric or string item is being input, 
the item is canceled. 

Example: See Appendix A, "BASIC Disk Input and Output," 
in the BASIC Handbook. 
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INPUTS 

Function 



Purpose: Returns a string of n characters, read from the 
keyboard or from file number filenum. 

Versions: Cassette Disk Advanced Compiler 



Format: v$ = INPUT$(w[,[#l/z7eyzww]) 

Remarks: 

n is the number of characters to be read 

from the file. 

filenum is the file number used on the OPEN 
statement. If filenum is omitted, the 
keyboard is read. 

If the keyboard is used for input, no characters are 
displayed on the screen. All characters (including 
control characters) are passed through except 
Ctrl-Break, which is used to interrupt the execution 
of the INPUTS function. When responding to 
INPUT$ from the keyboard, it is not necessary to 
press Enter. 

The INPUTS function allows you to read characters 
from the keyboard that are significant to the BASIC 
Program Editor, such as Backspace (ASCII code 8). 
If you want to read these special characters, you 
should use INPUTS or INKEYS (not INPUT or 
LINE INPUT). 

For communications files, the INPUTS function is 
preferred over the INPUT # and LINE INPUT # 
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INPUTS 

Function 

statements, since all ASCII characters can be 
significant in communications. See also Appendix C, 
"Communications." ( 

Example: The following program lists the contents of a 
sequential file in hexadecimal. 

10 OPEN "DATA" FOR INPUT AS #1 

20 IF E0F(1) THEN 50 

30 PRINT HEX$(ASC(INPUT$(1,#1))); 

40 GOTO 20 

50 PRINT 

60 END 

The next example reads a single character from the 
keyboard in response to a question. 

100 PRINT "TYPE P TO PROCEED OR S TO STOP" 

110 X$=INPUT$(1) 

120 IF X$="P" THEN 500 ( 

130 IF X$="S" THEN 700 ELSE 100 
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INSTR 

Function 



Purpose: 



Versions: 



Searches for the first occurrence of string j># in x$ 
and returns the position at which the match is found. 
The optional offset n sets the position for starting the 
search in x$ 



Cassette 

*** 



Disk 

*** 



Advanced 

*** 



Compiler 

*** 



Format: 
Remarks: 



v = INSTR([«,]jc&.y#) 



x$, y$ 



is a numeric expression in the range 1 to 

255. 

can be string variables, string expressions, 
or string constants. 



If rt>LEN(.x$), or if x$ is null, or if y$ cannot be 
found, INSTR returns 0. If y$ is null, INSTR returns 
n (or 1 if n is not specified). 

If n is out of range, an Illegal function call error is 
returned. 

Example: This example searches for the string "B" within the 
string "ABCDEB". When the string is searched from 
the beginning, "B" is found at position 2; when the 
search starts at position 4, "B" is found at position 6. 

10 A$ = "ABCDEB" 

20 B$ = "B" 

30 PRINT INSTR(A$,B$);INSTR(4,A$,B$) 
RUN 
2 6 
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INT 

Function 



Purpose: Returns the largest integer that is less than or equal 
to x. 

Versions: Cassette Disk Advanced Compiler 

Format: v = INT(;c) 

Remarks: x is any numeric expression. 

This is called the "floor" function in some other 
programming languages. 

See also "FIX" and "CINT" functions. (They also 
return integer values.) 

Example: This example shows how INT truncates positive 

integers, but rounds negative numbers upward (in a 
negative direction). 

PRINT INK45.67) 

45 
PRINT INTC-2.89) 
-3 
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IOCTL 
Statement 



Purpose: Allows BASIC to send a control data string to a 
device driver anytime after the driver has been 
OPENed. 

Not valid for BASIC releases earlier than 3.0. 



Versions: Cassette 



Disk Advanced Compiler 



Format: IOCTL [#]filenum,string 
Remarks: 

filenum is the filenumber for the device driver. 

string is a string expression containing the 
control data. 

BASIC'S file I/O system allows you to create and 
install your own device drivers. The IOCTL 
statement and the IOCTL$ function send control 
data to and read data from your device driver. 

An IOCTL command string can be up to 255 bytes 
long. Multiple commands within the string can be 
separated by semicolons: 

"Li-';; 3 L66;LWi32" 

You define the content and format of the control 
data string. The possible commands are determined 
by the characteristics of the driver installed. 
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IOCTL 
Statement 

Example: Initially, character device drivers for LPT1:, LPT2:, 
and LPT3 : are installed, but they can be replaced. If 
you install a driver called LPT1 to replace LPT1: and 
that driver is able to set page length, an IOCTL 
command string to set or change the page length 
might be: 

"PLn" (where n is the new page length). 

You can then open the new LPT1 driver and set the 
page length with: 

OPEN "LPT1" FOR OUTPUT AS #1 
IOCTL #1, "PL60" 

You could, for instance, write a device driver that 
controls a monitor and is capable of setting the mode 
of the screen to color and also capable of setting the 
width of the screen. For example: 

OPEN "OPT" FOR OUTPUT AS #2 
IOCTL #2, "CL:W40" 

Assuming that your new driver accepts a command 
called "CL" to change the screen to color and a 
command called "W«" to set the width of the screen, 
the previous example passes those commands to your 
driver and causes the screen to respond. 

Note: For related information, see "IOCTL$ 
Function" in this manual, "Device Drivers" in 
the BASIC Handbook, and the device driver 
section of Disk Operating System Technical 
Reference. 
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IOCTL$ 
Function 



Purpose: Reads a control data string from a device driver that 
is open. 

Not valid for BASIC releases earlier than 3.0. 

Versions: Cassette Disk Advanced Compiler 

Format: v$ = IOCTL$([#l/Vfe/iww) 
Remarks: 

filenum is the number of the file open to the 

device. 

The IOTCL$ function can be used to get 
acknowledgment that an IOCTL command has 
succeeded or failed. It can also be used to get device 
configuration information, such as device width. 

Example: This example checks to see if control data was 
successfully received. 

10 OPEN "COM" AS #1 

20 IOCTL #1, "SW132;GW" 

30 IF I0CTL$(1) = "132" 

THEN PRINT "WIDTH SET SUCCESSFULLY" 

If the device driver "COM" returns a value not 
equal to 132 from the IOCTL$ request, your 
command was not processed successfully and you 
should check for errors. If a device failure occurs, 
check "the system variables of ERDEV and 
ERDEV$. 
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KEY 

Statement 

Purpose: Sets or displays the soft keys. 



Advanced 



Compiler 



Versions: Cassette Disk 

Format: KEY ON 

KEY OFF 



KEY LIST 

KEY n, x$ 

KEY n, CtfR$(KB/ lag) and CHR$(scd« code) (For 
Advanced BASIC 2.0 and later releases.) 

Remarks: KEY ON causes the soft key values to be displayed 
on the 25th line. When the width is 40, 5 of the 10 
soft keys are displayed. When the width is 80, all 10 
are displayed. In either width, only the first 6 
characters of each value are displayed. 

KEY OFF erases the soft key display from the 25 th 
line, making that line available for program use. It 
does not disable the function keys. 

After turning off the soft key display with KEY 
OFF, you can use LOCATE 25,1 followed by 
PRINT to display anything you want on the bottom 
line of the screen. Information on line 25 is not 
scrolled, as are lines 1 through 24. 
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KEY 

Statement 

KEY LIST lists all 1 soft key values on the screen. 
All 1 5 characters of each value are displayed. 

KEY n,x$ allows you to set each function key to 
automatically type any sequence of characters. ON 
is the default state for the soft key display. 

n is the function key number in the range 1 to 

10. 

x$ is a string expression that is assigned to the 

key. (Remember to enclose string constants in 
quotation marks.) 

The value of a function key n is reassigned the value 
of the string x%. If the value entered for n is not in 
the range 1 to 10, an Illegal function call error occurs. 
The previous key string assignment is retained. x$ 
can be 1 to 1 5 characters in length. If it is longer 
than 15 characters, only the first 15 characters are 
assigned. 

Assigning a null string to a soft key disables the 
function key as a soft key. 

When a soft key is pressed, the INKEY$ function 
returns one character of the soft key string each time 
it is called. The first character is binary zero, the 
second is the key scan code, as listed in Appendix D, 
"ASCII Character Codes." 
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KEY 

Statement 



There are also six definable key traps. With this 
capability, you can trap any Ctrl, Shift, or super-shift 
key. (For Advanced BASIC 2.0 and later releases.) 

These additional keys are defined by the statement: 

KEY n,CHR$(KBflag)+CHR$(scan code) 

n is a numeric expression in the range 1 5 

to 20. 

KB flag is a mask for the latched keys. The 

appropriate bit in KB flag must be set in 
order to trap a key that is shifted, 
Alt-shifted, or Ctrl-shifted. The KBflag 
values in hex are : 

Caps Lock &H0-Caps Lock is not active. 

Caps Lock &H40-Caps Lock is active. 

Num Lock &H0-Num Lock is not active. 

Num Lock &H20-Num Lock is active. 

Alt &H08-ALT key is pressed. 

Ctrl &H04-Control key is pressed. 

Left Shift &H02-Left Shift key is pressed. 

Right Shift &H01 -Right Shift is pressed. 

Scan code is the number identifying one of the 83 
keys to trap. See Appendix E, "Scan 
Codes." 
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KEY 

Statement 

Note that key trapping assumes that the left and right 
Shift keys are the same, so you can use a value of 
&H01, &H02, or &H03 (the sum of hex 01 and hex 
02) to denote a Shift key. 

You can also add multiple shift states. For example, 
the Ctrl and Alt keys can be added together. Shift 
state values must be in hex. 

When trapping a key or key combinations, you must 
know the state of Num. Lock and Caps Lock. 

When you trap keys, they are processed in the 
following order: 

1. Ctrl-PrtSc, which activates the line printer, is 
processed first. Even if Ctrl-PrtSc is defined as a 
trappable key, this does not prevent characters 
from being echoed to the line printer. 

2. Next, the function keys Fl to F10, Cursor Up, 
Cursor Down, Cursor Right, and Cursor Left 
(1-14) are processed. Setting scan codes 59 to 
68, 72, 75, 77, or 80 as key traps has no effect, 
because they are considered to be predefined. 

3. Last, the keys you define for 15 to 20 are 
processed. 

Notes: 

• Trapped keys do not go into the BIOS buffer so 
that only BASIC will know that the keys were 
pressed. 

• Be careful when you trap Ctrl-Break and 
Ctrl-Alt-Del, because unless you have a test in 
your trap routine, you will have to turn the power 
off to stop your program- 
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KEY 

Statement 

The following entry, "KEY(n) Statement," explains 
how to enable and disable function key trapping in 
Advanced BASIC. 

Example: This example displays the soft keys on the 25th line. 

50 KEY ON 

This example erases soft-key display. The soft keys 
are still active, but not displayed. 

10 KEY OFF 

This example assigns the string "FILES" +Enter to 
soft key 1 . This is a way to assign a commonly used 
command to a function key. 

10 KEY 1,"FILES"+CHR$(13) 

This example disables function key 1 as a soft key. 

10 KEY 1,"" 
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KEY 

Statement 

This example sets up a Key trap for capital P. Note 
that all three KEY statements - KEY, KEY(n), and 
ON KEY — are used with key trapping. 

10 KEY 15, CHR$(&H40)+CHR$(25) 
20 ON KEY(15) GOSUB 1000 
30 KEY(15) ON 

This example sets up a Key trap for Ctrl-Shift A. 
Notice that the hex values for Ctrl (&H04) and Shift 
(&H03) are added together to get the shift state. 

10 KEY 20, CHR$(&H04+&H03)+CHR$(30) 
20 ON KEY(20) GOSUB 2000 
30 KEY(20) ON 
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KEY(n) 
Statement 



Purpose: Activates and deactivates trapping of the specified 
key in a BASIC program. See "ON KEY(n) 
Statement." 

Versions: Cassette Disk Advanced Compiler 

*** r**\ 

Format: KEY(rc) ON 
KEY(w) OFF 
KEY(rc) STOP 



Remarks: 



n is a numeric expression in the range 1 to 20, 

and indicates the trapped key: 

1-10 function keys F 1 to F 1 

1 1 Cursor Up 

12 Cursor Left 

13 Cursor Right 

14 Cursor Down 

15-20 keys defined by the form: 

KEY n,CHR$(KBflag) + CHR$(scan code). 
Keys 15-20 can be trapped in Advanced 
BASIC 2.0 and later releases. 

KEY(«) ON must be executed to activate trapping of 
function key or cursor control key activity. After 
KEY(/i) ON, if a nonzero line number is specified in 
the ON KEY(rc) statement, then every time BASIC 
starts a new statement it checks to see if the 
specified key was pressed. If so it performs a 
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KEY(n) 
Statement 

GOSUB to the line number specified in the ON 
KEY(n) statement. A KEY(n) statement cannot 
precede an ON KEY(«) statement. 

If KEYO) is OFF, no trapping takes place and even 
if the key is pressed, the event is not remembered. 

Once a KEY(n) STOP statement has been executed, 
no trapping takes place. However, if you press the 
specified key your action is remembered, so that an 
immediate trap takes place when KEY(«) ON is 
executed. 

KEY(a?) ON has no effect on whether the soft key 
values are displayed at the bottom of the screen. 

If you use a KEY(n) statement in Cassette BASIC or 
Disk BASIC, a Syntax error occurs. See also "KEY 
Statement." 
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KILL 

Command 



Purpose: Deletes a file from a disk. The KILL command in 
BASIC is similar to the ERASE command in DOS. 



Versions: Cassette 



Disk Advanced Compiler 



Format: KILL filespec 
Remarks: 



filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. Filespec 
must conform to the rules outlined 
under Naming Files in Chapter 3 of the 
BASIC Handbook; otherwise, an error 
occurs. 



KILL can be used for all types of disk files. The 
name must include the extension, if one exists. For 
example, you can save a BASIC program using the 
command 

SAVE "TEST" 

BASIC supplies the extension .BAS for the SAVE 
command, but not for the KILL command. If you 
want to delete that program file later, you must say 
KILL "TEST.BAS", not KILL "TEST". 

If a KILL statement is given for a file that is 
currently open, a File already open error occurs. 
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KILL 

Command 

Example: To delete the file named "DATA1" on drive A, you 
might use: 

200 KILL "A:DATA1" 

To delete the file "PROG.BAS" in the LEVEL2 

subdirectory, you might use: 

KILL "LEVEL1\LEVEL2\PR0G.BAS" 

Note that KILL can be used only to delete files. 
The RMDIR command must be used to remove 
directories. 
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LEFTS 
Function 



Purpose: Returns the leftmost n characters of x$. 



Versions: Cassette Disk 



Advanced Compiler 



Format: 
Remarks: 



v$ = LEFTS (x$,n) 



x$ is any string expression. 

n is a numeric expression that must be in the 

range to 255. It specifies the number of 
characters that are to be in the result. 

If n is greater than LEN(;c#), the entire string (x$) is 
returned. If n=0, the null string (length zero) is 
returned. 

See also "MID$" and "RIGHTS" functions. 

Example: In this example, the LEFT$ function is used to 
extract the first five characters from the string 
"BASIC PROGRAM". 

10 A$ = "BASIC PROGRAM" 

20 B$ = LEFT$(A$,5) 

30 PRINT B$ 

RUN 

BASIC 
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LEN 
Function 



Purpose: Returns the number of characters in x$. 
Versions: Cassette Disk Advanced Compiler 

Format: v = LEN(x#) 

Remarks: x$ is any string expression. 

Unprintable characters and blanks are included in 
the count of the number of characters. 

Example: There are 14 characters in the string "BOCA 
RATON, FL" because the comma and the two 
blanks are counted. 

10 X$ = "BOCA RATON, FL" 
20 PRINT LEN(X$) 
RUN 
14 
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LET 

Statement 

Purpose: Assigns the value of an expression to a variable. 
Versions: Cassette Disk Advanced Compiler 

Format: [LET] variable = expression 

Remarks: 

variable is the name of the variable or array 

element that is to receive a value. It 
can be a string or numeric variable or 
array element. 

expression is the expression whose value is 

assigned to variable. The type of the 
expression (string or numeric) must 
match the type of the variable, or a 
Type mismatch error occurs. 
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LET 

Statement 



The word LET is optional; that is, the equal sign is 
enough when assigning an expression to a variable 
name. 

Example: This example assigns the value 12 to the variable 
DORI. It then assigns the value 14, which is the 
value of the expression DORI +2, to the variable E. 
The string "HORA" is assigned to the variable 
FDANCE$. 

10 LET D0RI=12 

20 LET E=D0RI+2 

30 LET FDANCE$="HORA" 

The same statements could have also been written: 

10 D0RI=12 

20 E=D0RI+2 

30 FDANCE$="HORA" 



155 



LINE 

Statement 

Purpose: Draws a line or a box on the screen. 
Versions: Cassette Disk Advanced Compiler 

Graphics mode only. 

Format: LINE [{xl,yl)] ~{x2,y2) [.[color] [,B[F]] [,style]\ 

Remarks: 

(xl,yl), (x2,y2) 

are coordinates in either absolute or 
relative form. See "Specifying 
Coordinates" under "Graphics Modes" 
in Chapter 3 of the BASIC Handbook. 

color is an integer expression. It chooses an 

attribute from the legal attribute range 
for the current screen mode. In medium 
resolution, the color is the current color 
for that attribute as defined by the 
COLOR statement. Four attributes 
(0-3) are available in medium 
resolution; in high resolution, two 
attributes (0-1) are available. Zero is 
always the attribute for the background. 
The default foreground attribute is 
always the maximum attribute for that 
screen mode: 3 in medium resolution; 1 
in high resolution. 

style is a 16-bit integer mask used to put 

points on the screen. The style option is 
used for normal lines and boxes, but 
cannot be used with filled boxes (BF). 



156 



LINE 

Statement 

Using style with BF results in a Syntax 
error. This technique is called line 
styling. (For BASIC 2.0 and later 
releases.) 

The simplest form of LINE is: 

LINE -(X2,Y2) 

This will draw a line from the last point referenced 
to the point (x2,y2) in the foreground attribute. 

We can include a starting point also: 

LINE (0,0)-(319,199) 'diagonal down screen 
LINE (0,100)-(319,100) 'horizontal bar 
across screen 

We can indicate the attribute in which to draw the 
line: 

LINE (10,10)-(20,20),2 'draw in attribute 2 



10 'draw random lines in random colors 

20 SCREEN 1,0,0,0: CLS 

30 LINE -(RND*319,RND*199),RND*4 

40 GOTO 20 



10 'alternating pattern - line on, line off 

20 SCREEN 1,0,0,0: CLS 

30 FOR X=0 TO 319 

40 LINE (X,0)-(X,199),X AND 1 

50 NEXT 

The next argument to LINE is B (box), or BF (filled 
box). We can leave out color and include the 
argument: 

LINE (0,0)-(100,100),,B 'box in foreground 
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LINE 

Statement 

or we can include the attribute: 

LINE (0,0)-(100,100),2,BF 
' filled box attribute 2 

The B tells BASIC to draw a rectangle with the 
points {xl,yl) and {x2,y2) as opposite corners. This 
avoids having to give the four LINE commands: 

LINE (X1,Y1)-(X2,Y1) 

LINE (X1,Y1)-(X1,Y2) 

LINE (X2,Y1)-(X2,Y2) 

LINE (X1,Y2)-(X2,Y2) 

that perform the equivalent function. 

The BF means "draw the same rectangle as B, but 
also fill in the interior points with the selected 
color." 

The last argument to LINE is style. LINE uses the 
current circulating bit in style to plot (or store) points 
on the screen. If the bit is (zero), no point is 
plotted. If the bit is 1 (one), a point is plotted. 
After each point, the next bit position in style is 
selected. When the last bit position has been 
selected, LINE "wraps around" and begins with the 
first bit again. 

Note that a (zero) bit indicates no store and does 
not erase the existing point on the screen. You may 
want to draw a background line before a styled line 
to force a known background. 

The style option can be used to draw a dotted line 
across the screen by plotting (storing) every other 
point. Because style is 1 6 bits wide, the pattern for a 
dotted line looks like this: 
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LINE 

Statement 

1010101010101010 

This is equal to HAAAA in hexadecimal notation. 

Examples: To draw a dotted line: 

10 SCREEN 1,0 

20 LINE (0,0)-(319,199),,,&HAAAA 

To draw a cyan box with dashes: 

10 SCREEN 1,0 

20 LINE (0,0)-(100,100),l,B,&HCCCC 

In BASIC release 1.1, out-of-range coordinates 
given to the LINE statement wrap-around to the 
next horizontal line. 

In BASIC 2.0 and later releases, out-of-range 
coordinates are clipped. 

The last point referenced after a LINE statement is 
point (x2,y2). If you use the relative form for the 
second coordinate, it is relative to the first 
coordinate. For example, 

LINE (100,100)-STEP (10,-20) 

draws a line from (100, 100) to (11 0,80). 

This example draws random boxes filled with random 
colors. 

10 CLS 

20 SCREEN 1,0: COLOR 0,0 

30 LINE -(RND*319,RND*199),RND*2+1,BF 

40 GOTO 30 'boxes will overlap 
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LINE INPUT 

Statement 



Purpose: Reads an entire line (up to 255 characters) from the 
keyboard into a string variable, ignoring delimiters. 

Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



LINE mPUT[;]["prompt"\] stringvar 



"prompt" is a string constant that is displayed on 
the screen before input is accepted. A 
question mark is not printed unless it is 
part of the prompt string. 

stringvar is the name of the string variable or 

array element to which the line will be 
assigned. All input from the end of the 
prompt to the Enter is assigned to 
stringvar. Trailing blanks are ignored. 

In Disk BASIC and Advanced BASIC, if LINE 
INPUT is immediately followed by a semicolon, then 
pressing Enter to end the input line does not produce 
a carriage return/line feed sequence on the screen. 
That is, the cursor remains on the same line as your 
response. 

You can exit LINE INPUT by pressing Ctrl-Break. 
BASIC returns to command level and displays Ok. 
You can then enter CONT to resume execution at 
the LINE INPUT. 

Example: See the example in the next entry, "LINE INPUT # 
Statement." 
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LINE INPUT* 

Statement 



Purpose: Reads an entire line (up to 255 characters), ignoring 
delimiters, from a sequential file into a string 
variable. 

Versions: Cassette Disk Advanced Compiler 



Format: LINE INPUT #filenum, stringvar 
Remarks: 

filenum is the number under which the file was 

opened. 

stringvar is the name of a string variable or array 
element to which the line will be 
assigned. 

LINE INPUT # reads all characters in the sequential 
file up to a carriage return. It then skips over the 
carriage return/line feed sequence, and the next 
LINE INPUT # reads all characters up to the next 
carriage return. (If a line feed/carriage return 
sequence is encountered, it is preserved. That is, the 
line feed/carriage return characters are returned as 
part of the string.) 

LINE INPUT # is especially useful if each line of a 
file has been broken into fields, or if a BASIC 
program saved in ASCII mode is being read as data 
by another program. 

See also Appendix A, "BASIC Disk Input and 
Output," in the BASIC Handbook. 
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LINE INPUT # 
Statement 

Example: The following example uses LINE INPUT to get 
information from the keyboard, where the 
information is likely to have commas or other 
delimiters. Then the information is written to a 
sequential file, and read back out from the file usin£ 
LINE INPUT #. 

10 OPEN "LST" FOR OUTPUT AS #1 

20 LINE INPUT "Address? ";C$ 

30 PRINT #1, C$ 

40 CLOSE 1 

50 OPEN "LST" FOR INPUT AS #1 

60 LINE INPUT #1, C$ 

70 PRINT C$ 

80 CLOSE 1 

RUN 

Address? 

Suppose you respond with DELRAY BEACH, FL 

33445. The program continues: 



Address? DELRAY BEACH, FL 33445 
DELRAY BEACH, FL 33445 
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LIST 
Command 



Purpose: Lists the program currently in memory on the screen 
or other specified device. 



Versions: Cassette Disk 



Advanced Compiler 



Format: LIST [linel] [-[line 2]] [, filespec] 



Remarks: 



linel, linel are valid line numbers in the range 
to 65529. linel is the first line to be 
listed. Hne2 is the last line to be 
listed. A period (.) can be used for 
either line number to indicate the 
current line. 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. 
Filespec must conform to the rules 
outlined under ''Naming Files" in 
Chapter 3 of the BASIC Handbook; 
otherwise, an error occurs. 

In Cassette BASIC, listings directed to the screen by 
omitting the device specifier can be stopped at any 
time by pressing Ctrl-Break. Listings directed to 
specific devices cannot be interrupted and will list 
until the range is too big. That is, LIST range can be 
interrupted, but LIST range, "SCRN:" cannot. 

In Disk BASIC and Advanced BASIC, any listing to 
either the screen or the printer can be interrupted by 
pressing Ctrl-Break. 
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LIST 

Command 



If the line range is omitted, the entire program is 
listed. 

When the dash (-) is used in a line range, three 
options are available: 

• If only linel is given, that line and all higher 
numbered lines are listed. 

• If only Une2 is given, all lines from the beginning 
of the program through Une2 are listed. 

• If both line numbers are specified, all lines from 
linel through Une2, inclusive, are listed. 

When you list to a file on cassette or disk, the 
specified part of the program is saved in ASCII 
format. This file can later be used with MERGE. 

BASIC always returns to the command level after a 
LIST is executed. 
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LIST 
Command 

Example: This example lists the entire program on the screen. 
LIST 

This example lists line 35 on the screen. 

LIST 35,"SCRN:" 

This example lists lines 10 through 20 on the 
printer. 

LIST 10-20, "LPT1 : " 

This example lists all lines from 1 00 through the 
end of the program to the first communications 
adapter at 1200 bps, no parity, 8 data bits, 1 stop 
bit. 

LIST 100- ,"COM1:1200,N,8" 

This example lists from the first line through line 
200 to a file named "BOB" on cassette. 

LIST -200,"CAS1:BOB" 
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LLIST 
Command 



Purpose: Lists all or part of the program currently in memory 
on the printer (LPT1:). 

Versions: Cassette Disk Advanced Compiler 

Format: LLIST [linel][- [Une2]] 

Remarks: The line number ranges for LLIST work the same as 
for LIST. 

BASIC always returns to command level after an 
LLIST is executed. 

Example: This example prints the entire program. 

LLIST 

This example prints line 35. 

LLIST 35 

This example prints lines 10 through 20. 

LLIST 10-20 

This example prints all lines from 100 through the 
end of the program. 

LLIST 100- 

This example prints the first line through line 200. 

LLIST -; 
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LOAD 
Command 



Purpose: Loads a program from the specified device into 
memory, and optionally runs it. 

Versions: Cassette Disk Advanced Compiler 

Format: LOAD filespec[,R] 

Remarks: 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. Filespec 
must conform to the rules outlined 
under "Naming Files" in Chapter 3 of 
the BASIC Handbook; otherwise, an 
error occurs and the load is canceled. 

LOAD closes all open files and deletes all variables 
and program lines currently residing in memory 
before it loads the specified program. If the R option 
is omitted, BASIC returns to direct mode after the 
program is loaded. 

However, if the R option is used with LOAD, the 
program runs after it is loaded. In this case all open 
data files are kept open. Thus, LOAD with the R 
option can be used to chain several programs (or 
segments of the same program). Information can be 
passed between the programs using data files. 

LOAD filespec,R is equivalent to RUN filespec. 

If you are using Cassette BASIC and the device 
name is omitted, CAS1: is assumed. CAS1: is the 
only device allowed for LOAD in Cassette BASIC. 



167 



LOAD 

Command 



If you are using Disk BASIC or Advanced BASIC, 
the DOS default disk drive is used if the device is 
omitted. The extension .BAS is added to the 
filename if no extension is supplied and the filename 
is eight characters or less. 

Notes when using CAS1 : 

1 . If the LOAD statement is entered in direct mode, 
the file names on the tape are displayed on the 
screen followed by a period (.) and a single letter 
indicating the type of file. This is followed by the 
message Skipped for the files not matching the 
named file, and Found when the named file is 
found. Types of files and their corresponding 
letter are: 

.B for BASIC programs in internal format 

(created with SAVE command) 
.P for protected BASIC programs in internal 

format (created with SAVE ,P command) 
.A for BASIC programs in ASCII format 

(created with SAVE ,A command) 
.M for memory image files (created with 

BSAVE command) 
.D for data files (created by OPEN followed 

by output statements) 

To see what files are on a cassette tape, rewind 
the tape and enter some name that is known not 
to be on the tape; for example, LOAD 
"CASlrNOWHERE". All filenames are then 
displayed. 

If the LOAD command is executed in a BASIC 
program, the filenames skipped and found are not 
displayed on the screen. 
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LOAD 
Command 

2. Note that Ctrl-Break can be typed at any time 
during LOAD. Between files or after a time-out 
period, BASIC exits the search and returns to 
command level. Previous memory contents 
remain unchanged. 

3. If CAS1 : is specified as the device and the 
filename is omitted, the next program file on the 
tape is loaded. 

Example: This example loads the program named MENU, but 
does not run it. 

LOAD "MENU" 

This example loads and runs the program INVENT: 

LOAD "INVENT", R 
which is equivalent to 

RUN "INVENT" 

This example loads the file VLAD.BAS from disk 
drive B. Note that the .BAS did not have to be 
specified. 

LOAD "B: VLAD.BAS" 

This example loads the next program on the tape. 

LOAD "CAS1:" 
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LOC 

Function 

Purpose: Returns the current position in the file. 
Versions: Cassette Disk Advanced Compiler 

Format: v = LOCifilenum) 

Remarks: 

filenum is the file number used when the file was 
opened. 

With random files, LOC returns the record number 
of the last record read or written to a random file 
since the file was opened. 

With sequential files, LOC returns the number of 
records read from or written to the file since it was 
opened. (A record for sequential files is a 128-byte 
block of data.) When a file is opened for sequential 
input, BASIC reads the first sector of the file, so 
LOC returns a 1 even before any input from the file. 

For a communications file, LOC returns the number 
of characters in the input buffer waiting to be read. 
The default size for the input buffer is 256 
characters, but you can change this with the /C: 
option in the BASIC command line. If more than 
255 characters are in the buffer, LOC returns 255. 
Since a string is limited to 255 characters, this 
practical limit means that you do not have to test for 
string size before reading data into it. If fewer than 
255 characters remain in the buffer, then LOC 
returns the actual count. 
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LOC 

Function 

Example: This example stops the program when the 50th 
record in the file is passed. 

100 IF LOC(1)>50 THEN STOP 

This example could be used to rewrite the record 
that was just read. 

100 PUT #1,L0C(1) 
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LOCATE 

Statement 



Purpose: Positions the cursor on the active screen. Optional 
parameters turn the blinking cursor on and off and 
define the size of the blinking cursor. 

Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



LOCATE [row][,[cof][,[cursor][,[start][,stop\\W 



row is a numeric expression in the range 1 to 

25. It indicates the screen line number 
where you want to place the cursor. 

col is a numeric expression in the range 1 to 

40 or 1 to 80, depending upon screen 
width. It indicates the screen column 
number where you want to place the 
cursor. 

cursor is a value indicating whether the cursor is 
visible or not. A (zero) indicates off, 1 
(one) indicates on. 

start is the cursor-start scan line. It must be a 

numeric expression in the range to 3 1 . 

stop is the cursor-stop scan line. It also must 

be numeric expression in the range to 
31. 

cursor, start, and stop do not apply to graphics mode. 

start and stop allow you to make the cursor any size 
you want. You indicate the starting and ending scan 
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LOCATE 

Statement 

lines. The scan lines are numbered from at the top 
of the character position. The bottom scan line is 7 
if you have the Color/Graphics Monitor Adapter, 13 
if you have the IBM Monochrome Display and 
Parallel Printer Adapter. If start is given and stop is 
omitted, stop assumes the value of start. If start is 
greater than stop, you'll get a two-part cursor. The 
cursor "wraps" from the bottom line back to the top. 

After a LOCATE statement, I/O statements to the 
screen begin placing characters at the specified 
location. 

When a program is running, the cursor is normally 
off. You can use LOCATE ,,1 to turn it back on. 

Normally, BASIC will not print to line 25. However, 
you can turn off the soft key display using KEY 
OFF, and then use LOCATE 25,1: PRINT... to put 
data on line 25. Line 25 does not scroll as the rest of 
the screen does. 

Any parameter can be omitted. Omitted parameters 
assume the current value. 

Any values entered outside the ranges indicated 
results in an Illegal function call error. Previous 
values are retained. 
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Statement 

Example: This example moves the cursor to the home position 
in the upper left-hand corner of the screen. 

10 LOCATE 1,1 

This example makes the blinking cursor visible; its 
position remains unchanged. 

10 LOCATE ,,1 

In this example, position and cursor visibility remain 
unchanged. The cursor is set to display at the 
bottom of the character on the Color/Graphics 
Monitor Adapter (starting and ending on scan line 

7). 

10 LOCATE ,,,7 

This example moves the cursor to line 5, column 1. 
It makes the cursor visible, covering the entire 
character cell on the Color/Graphics Monitor 
Adapter, starting at scan line and ending on scan 
line 7. 

10 LOCATE 5,1,1,0,7 
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LOF 

Function 



Purpose: Returns the number of bytes allocated to the file 
(length of the file). 

Versions: Cassette Disk Advanced Compiler 

Format: v = LOF(filenum) 

Remarks: 

filenum is the file number used when the file was 
opened. 

For disk files created by BASIC 1.10, LOF returns a 
multiple of 128. For example, if the actual data in 
the file is 257 bytes, the number 384 is returned. 
For disk files created outside BASIC (for example, 
by using EDLIN), and for files created by BASIC 
2.0 and later releases, LOF returns the actual 
number of bytes allocated to the file. 

For communications, LOF returns the amount of 
free space in the input buffer. That is, 
size-LOC (filenum), where size is the size of the 
communications buffer, which defaults to 256 but 
can be changed with the /C: option in the BASIC 
command line. Use of LOF can be used to detect 
when the input buffer is getting full. In practicality, 

LOC is adequate for this purpose, as demonstrated 
in the example in Appendix C, "Communications." 
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LOF 

Function 

Example: These statements get the last record of the file 

named BIG (if BIG was created with a record length 
of 128 bytes): 

10 OPEN "BIG" AS #1 
20 GET #1,L0F(1)/128 
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LOG 
Function 



Purpose: Returns the natural logarithm of x. 



Versions: Cassette Disk 



Advanced Compiler 



Format: v = LOG(x) 

Remarks: 

x must be a numeric expression greater than 

zero. 

The natural logarithm is the logarithm to the base e. 
In BASIC 2.0 and later releases, you can have this 
calculation performed in double-precision by 
specifying /D in the BASIC command line when 
BASIC is initially loaded. See "Options in the 
BASIC Command Line" in the BASIC Handbook. 

Example: The first example calculates the logarithm of the 
expression 45/7: 

PRINT L0G(45/7) 
1.860752 

The second example calculates the logarithm of e 
and of e 2 : 

E= 2.718282 
? LOG(E) 

1 
? L0G(E*E) 

2 
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LPOS 

Function 



Purpose: Returns the current position of the print head within 
the printer buffer for LPT1:. 

Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



v = LPOS(«) 



Example: 



0orl 

2 
3 



is a numeric expression that is a dummy 
argument in Cassette BASIC. In Disk BASIC 
and Advanced BASIC, n indicates the printer 
being tested, as follows: 



LPT1 
LPT2 
LPT3 



Therefore, we recommend you use or 1 in Cassette 
BASIC to maintain compatibility with the other 
versions. 

The LPOS function does not necessarily give the 
physical position of the print head on the printer. 

In this example, if the line length is more than 60 
characters a carriage return character is sent to the 
printer so it skips to the next line. 

100 IF LPOS(0)>60 THEN LPRINT CHR$(13) 
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LPRINT and LPRINT USING 

Statements 



Purpose: Prints data on the printer (LPT1:). 



Versions: 



Cassette 



Disk 

*** 



Advanced 

*** 



Compiler 

*** 



Format: LPRINT [list of expressions [;] 

LPRINT USING v$; list of expressions [;] 

Remarks: 

list of expressions 

is a list of the numeric and/or string 
expressions to be printed. The expressions 
must be separated by commas or semicolons. 

expression is a numeric or string expression whose 
value is to be printed. 

v$ is a string constant or variable that identifies 
the format to be used for printing. This is 
explained in detail under "PRINT Statement." 

These statements function like PRINT and PRINT 
USING, except output goes to the printer. See 
"PRINT" and "PRINT USING" statements. 

LPRINT assumes an 80-character-wide printer. 
That is, BASIC automatically inserts a carriage 
return/line feed after printing 80 characters. This 
means that two lines are skipped when you print 
exactly 80 characters, unless you end the statement 
with a semicolon. You can change the width value 
with a WIDTH "LPT1:" statement. 
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LPRINT and LPRINT USING 
Statements 

If you do a form feed (LPRINT CHR$(12);) 
followed by another LPRINT and the printer takes 
more than 10 seconds to do the form feed, you can 
get a Device timeout error on the second LPRINT. 
To avoid this problem, enter the following: 

1 ON ERROR GOTO 65000 



65000 IF ERR = 24 THEN RESUME '24=timeout 

You may want to test ERR to make sure the 
timeout was caused by an LPRINT statement. 

Example: This is an example of sending special control 

characters to the IBM 80 CPS Matrix Printer using 
LPRINT and CHR$. The printer control characters 
are listed in the IBM Personal Computer Technical 
Reference manual. 

10 LPRINT CHR$(14) ;" Title Line" 

20 FOR 1=2 TO 4 

30 LPRINT "Report line" ;I 

40 NEXT I 

50 LPRINT CHR$(15); "Condensed print;132 

char/1 ine" 
60 LPRINT CHR$(18);"Return to normal" 
70 LPRINT CHR$(27);"E" 
80 LPRINT "This is emphasized print" 
90 LPRINT CHR$(27);"F" 
100 LPRINT "Back to normal again" 
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LPRINT and LPRINT USING 

Statements 

The output produced by this program looks like this: 

'!"" i. fc I. €5? 8 ± a— h e 

Report .1 i ne 2 
Report I i ne 3 
Report line 4 
Condensed print; 132 char/line 
R e t u r n t. o n o r m a 1 

This is emphasized print 

B a c k t o n o r m a .1 a g a i n 
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LSET and RSET 

Statements 



Purpose: Moves data into a random file buffer in preparation 
for a PUT (file) statement. 



Versions: Cassette 



Disk Advanced Compiler 



Format: LSET stringvar = x$ 
RSET stringvar = x$ 
Remarks: 



stringvar is the name of a variable defined in a 
FIELD statement. 

x$ is a string expression to place the 

information into the field identified by 
stringvar. 

If x$ requires fewer bytes than were specified for 
stringvar in the FIELD statement, LSET left-justifies 
the string in the field, and RSET right-justifies the 
string. (Spaces are used to pad the extra positions.) 
If x$ is longer than stringvar, characters are dropped 
from the right. 

Numeric values must be converted to strings before 
they are LSET or RSET. See "MKI$, MKS$, 
MKD$ Functions." 

See also Appendix A, "BASIC Disk Input and 
Output," in the BASIC Handbook for a complete 
explanation of using random files. 
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LSET and RSET 
Statements 

Note: LSET or RSET can also be used with a 
string variable that was not defined in a FIELD 
statement to left-justify or right-justify a string in 
a given field. For example, the program lines: 

10 A$=SPACE$(20) 
20 RSET A$=N$ 

right-justify the string N$ in a 20-character 
field. This can be useful for formatting printed 
output. 

Example: This example converts the numeric value AMT into a 
string, and left- justifies it in the field A$ in 
preparation for a PUT (file) statement. 

10 LSET A$=MKS$(AMT) 
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MERGE 

Command 



Purpose: Merges the lines from an ASCII program file into the 
program currently in memory. 

Versions: Cassette Disk Advanced Compiler 

Format: MERGE filespec 

Remarks: 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. Filespec 
must conform to the rules outlined 
under "Naming Files" in Chapter 3 of 
the BASIC Handbook; otherwise, an 
error occurs. 

The device is searched for the named file. If found, 
the program lines in the device file are merged with 
the lines in memory. If any lines in the file being 
merged have the same line number as lines in the 
program in memory, the lines from the file replace 
the corresponding lines in memory. 

After the MERGE command, the merged program 
resides in memory, and BASIC returns to command 
level. 

In Cassette BASIC, if the device name is omitted, 
CAS1: is assumed. CAS1: is the only device allowed 
for MERGE in Cassette BASIC. With Disk BASIC 
and Advanced BASIC, if the device name is omitted, 
the DOS default drive is assumed. 
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MERGE 

Command 

If CASl: is specified as the device name and the 
filename is omitted, the next ASCII program file 
encountered on the tape is merged. 

If the program being merged was not saved in ASCII 
format (using the A option on the SAVE command), 
a Bad file mode error occurs. The program in 
memory remains unchanged. 

Example: This example merges the file named "NUMBRS" on 
drive A with the program in memory. 

MERGE "A:NUMBRS" 
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MID$ Function and 
Statement 



Purpose: Returns the requested part of a given string. When 
used as a statement, as in the second format, replaces 
a portion of one string with another string. 

Versions: Cassette Disk Advanced Compiler 

Format: As a function: 

v$ = MlD$(x$,n[,m]) 
As a statement: 
MID$(v&/z[,m]) =y$ 
Remarks: For the function (v$=MID$...): 

x$ is any string expression. 

n is an integer expression in the range 1 to 255. 

m is an integer expression in the range to 255. 

The function returns a string of length m characters 
from x$ beginning with the nth character. If m is 
omitted or if fewer than m characters are to the right 
of the nth character, all rightmost characters 
beginning with the nth character are returned. If m 
is equal to 0, or if n is greater than LEN(x#), then 
MID$ returns a null string. 

See also "LEFT$" and "RIGHTS" functions. 



186 



MID$ Function and 
Statement 

For the statement (MID$...=y$) 

v$ is a string variable or array element that will 
have its characters replaced. 

n is an integer expression in the range 1 to 255. 

m is an integer expression in the range to 255. 

y$ is a string expression. 



The characters in v$, beginning at position n, are 
replaced by the characters iny$. The optional m 
refers to the number of characters from y$ used in 
the replacement. If m is omitted, all of y$ is used. 

However, regardless of whether m is omitted or 
included, the length of v$ does not change. For 
example, if v$ is four characters long and y$ is five 
characters long, then after the replacement v$ 
contains only the first four characters of y$. 

Note: If either n or m is out of range, an Illegal 
function call error is returned. 
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MID$ Function and 
Statement 

Example: The first example uses the MID$ function to select 
the middle portion of the string B$. 

10 A$="G00D " 

20 B$="M0RNING EVENING AFTERNOON" 

30 PRINT A$;MID$(B$,9,7) 

RUN 

GOOD EVENING 

The next example uses the MID$ statement to 
access substrings imbedded within one large string. 
This technique reduces fragmentation of string space. 

10 RECORDS = STRING$(255,0) 
20 PARTI. OFF = 1 
30 PARTI. LEN = 5 
40 PART2.0FF = 6 
50 PART2.LEN = 15 



100 MID$(RECORD$, PARTI. OFF, PARTI. LEN) = "STRNG 1 



188 



MKDIR 

Command 



Purpose: Creates a directory on the specified disk. (For 
BASIC 2.0 and later releases.) 

Versions: Cassette Disk Advanced Compiler 

Format: MKDIR path 

Remarks: 

path is a string expression, not exceeding 63 

characters, that identifies the new directory to 
be created. For more information about paths 
refer to "Naming Files" and "Tree-Structured 
Directories" in Chapter 3 of the BASIC 
Handbook. 

Example: This example creates, from the root directory, a 
subdirectory called SALES: 

MKDIR "SALES" 

This example creates, from the root directory, a 
subdirectory called MIKE under the directory 
SALES: 

MKDIR "SALES\MIKE" 

This example creates, from the root directory, a 
subdirectory called ALICE under the directory 
MIKE: 

MKDIR "SALES\MIKE\ALICE" 

This example creates, from the root directory, a 
subdirectory called ACCTING: 
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MKDIR 

Command 



MKDIR "ACCTING" 

This example makes ACCTING the current 
directory; then creates two subdirectories called 
SHANNON and CHELLE: 

CHDIR "ACCTING" 
MKDIR "SHANNON" 
MKDIR "CHELLE" 

The same structure can be created from the root by 
entering: 

MKDIR "ACCTINGXSHANNON" 
MKDIR "ACCTINGXCHELLE" 

By following the above examples, you create a tree 
structure that looks like this: 



ROOT 



SALES ACCTING 



MIKE SHANNON CHELLE 



ALICE 
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MKI$, MKS$, MKD$ 

Functions 



Purpose: Convert numeric type values to string type values. 
Versions: Cassette Disk Advanced Compiler 



Format: v$ = MKl$(integer expression) 

v$ = MKS$(single-precision expression) 

v$ = MKD$(double-precision expression) 

Remarks: Any numeric value that is placed in a random file 
buffer with an LSET or RSET statement must be 
converted to a string. MKI$ converts an integer to a 
2-byte string. MKS$ converts a single-precision 
number to a 4-byte string. MKD$ converts a 
double-precision number to an 8-byte string. 

These functions differ from STR$ because they do 
not really change the bytes of the data - just the way 
BASIC interprets those bytes. 

See also "CVI, CVS, CVD Functions" in this 
manual and Appendix A, "BASIC Disk Input and 
Output," in the BASIC Handbook. 
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MKI$, MKS$, MKD$ 

Functions 

Example: This example uses a random file (#1) with fields 

defined in line 100. The first field, D$, is intended 
to hold a numeric value, AMT. Line 1 1 converts 
AMT to a string value using MKS$ and uses LSET 
to place what is really the value of AMT into the 
random file buffer. Line 1 20 places a string into the 
buffer (it is not necessary to convert a string) ; then 
line 130 writes the data from the random file buffer 
to the file. 

100 FIELD #1, 4 AS D$, 20 AS N$ 

110 LSET D$ = MKS$(AMT) 

120 LSET N$ = A$ 

130 PUT #1 
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MOTOR 
Statement 



Purpose: Turns the cassette player on and off. 



Versions: 


Cassette Disk Advanced Compiler 




*** *** *** 


Format: 


MOTOR [state] 


Remarks: 






state is a numeric expression indicating on or 




off. 



If state is nonzero, the cassette motor is turned on. If 
state is zero, the cassette motor is turned off. 

If state is omitted, the cassette motor state is 
switched. That is, if the motor is off, it is turned on 
and vice versa. 

Example: The following sequence of statements turns the 
cassette motor on, then off, then back on again. 

10 MOTOR 1 
20 MOTOR 
30 MOTOR 
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NAME 
Command 



Purpose: Changes the name of a disk file. The NAME 
command in BASIC is similar to the RENAME 
command in DOS. 



Versions: Cassette 



Disk 



Advanced 



Compiler 



Format: NAME filespec AS filespec 

Remarks: 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. Filespec 
must conform to the rules outlined 
under "Naming Files" in Chapter 3 of 
the BASIC Handbook; otherwise, an 
error occurs. 

filespec is the new filespec. It must be a valid 

filespec as outlined in the same section. 

The file specified by filespec must exist and filename 
must not exist on the disk; otherwise, an error 
results. If the device name is omitted, the DOS 
default drive is assumed. Note that the file extension 
does not default to .BAS. 

After a NAME command, the file exists on the same 
disk, in the same disk space, with the new name. 
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NAME 

Command 

Example: In this example, the file that was formerly named 
ACCTS.BAS on the disk in drive A is now named 
LEDGER.BAS. 

NAME "A.-ACCTS.BAS" AS "LEDGER.BAS" 
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NEW 




Command 


Purpose: 


Deletes the program currently in memory and clears 
all variables. 


Versions: 


Cassette Disk Advanced Compiler 


Format: 


NEW 


Remarks: 


NEW is usually used to remove a program from 



memory before entering a new program. BASIC 
always returns to command level after NEW is 
executed. NEW causes all files to be closed and 
turns trace off if it was on. See also "TRON and 
TROFF Commands." 

Example: This example deletes the program in memory. 

NEW 
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OCT$ 
Function 



Purpose: Returns a string that represents the octal value of the 
decimal argument. 



Versions: Cassette Disk 



Advanced Compiler 



Format: 
Remarks: 



v$ = OCT$(«) 



n is a numeric expression in the range -32768 to 

65535. 

If n is negative, the twos complement form is used. 
That is, OCT$(-«) is the same as OCT$(65536-«). 

See "HEX$ Function" for hexadecimal conversion. 

Example: This example shows that 24 in decimal is 30 in octal. 

PRINT 0CT$(24) 
30 
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ON COM(n) 
Statement 



Purpose: Sets up a line number for BASIC to trap to when 

there is information coming into the communications 
buffer. 



Compiler 



Versions: Cassette Disk Advanced 

*** 

Format: ON COM(«) GOSUB line 
Remarks: 



n is the number of the communications adapter 

(1 or 2). 

line is the line number of the beginning of the trap 
routine. Setting line equal to (zero) 
disables trapping of communications activity 
for the specified adapter. 

A COM(tt) ON statement must be executed to 
activate this statement for adapter n. After COM(n) 
ON, if a nonzero line number is specified in the ON 
COM («) statement, then every time the program 
starts a new statement, BASIC checks to see if any 
characters have come in to the specified 
communications adapter. If so, BASIC performs a 
GOSUB to the specified line. 

If COM(n) OFF is executed, no trapping takes place 
for the adapter. Even if communications activity 
does take place, the event is not remembered. 

If a COM(n) STOP statement is executed, no 
trapping takes place for the adapter. However, any 
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ON COM(n) 
Statement 



characters being received are remembered so an 
immediate trap takes place when COM(n) ON is 
executed. 

When the trap occurs, an automatic COM(n) STOP 
is executed so that recursive traps never take place. 
The RETURN from the trap routine automatically 
does a COM(«) ON unless an explicit COM(n) OFF 
was performed inside the trap routine. 

Event trapping does not take place when BASIC is 
not executing a program. When an error trap 
(resulting from an ON ERROR statement) takes 
place, all trapping is automatically disabled 
(including ON COM, ON ERROR, ON PEN, ON 
PLAY, ON STRIG, and ON TIMER). 

Typically, the communications trap routine reads an 
entire message from the communications line before 
returning. It is not recommended that you use the 
communications trap for single character messages, 
since at high baud rates the overhead of trapping and 
reading for each individual character allows the 
interrupt buffer for communications to overflow. 

You can use RETURN line if you want to go back to 
the BASIC program at a fixed line number. This 
nonlocal return must be used with care, however, 
since any other GOSUBs, WHILEs, or FORs active 
at the time of the trap remain active. 



Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. This 
insures that every iteration of a FOR has a 
corresponding NEXT and every iteration of a 
WHILE has a corresponding WEND. 
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ON COM(n) 
Statement 



Example: 



150 ON C0M(1) GOSUB 500 
160 C0M(1) ON 



500 'incoming characters 



590 RETURN 300 

This example sets up a trap routine for the first 
communications adapter at line 500. 
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ON ERROR 

Statement 



Purpose: Enables error trapping and specifies the first line of 
the error handling subroutine. 

Versions: Cassette Disk Advanced Compiler 
Format: ON ERROR GOTO line 



Remarks: 



line is the line number of the first line of the error 
trapping routine. If the line number does not 
exist, an Undefined line number error results. 

Once error trapping has been enabled, all errors 
detected (including direct mode errors) will cause a 
jump to the specified error handling subroutine. 

To disable error trapping, execute an ON ERROR 
GOTO 0. Subsequent errors print an error message 
and halt execution. An ON ERROR GOTO 
statement that appears in an error trapping 
subroutine causes BASIC to stop and print the error 
message for the error that caused the trap. It is 
recommended that all error-trapping subroutines 
execute an ON ERROR GOTO if an error is 
encountered for which there is no recovery action. 

BASIC considers itself to be within the error 
trapping routine from the time an error occurs. It 
branches to the line specified by the ON ERROR 
statement until a RESUME statement is 
encountered. You must use the RESUME statement 
to exit from the error trapping routine. See also 
"RESUME Statement." 
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ON ERROR 

Statement 

Because error trapping does not occur within the 
error trapping routine, an ON ERROR GOTO line 
(within the error trapping routine), where line is 
anything other than 0, will not work. 

Note: If an error occurs during execution of an 
error handling subroutine, the BASIC error 
message is printed and execution terminates. 
Error trapping does not occur within the error 
handling subroutine. 

Example: This example tests to see if the drive door is open 
when the program needs to open a file. 

10 ON ERROR GOTO 100 

20 OPEN "DATA" FOR INPUT AS #1 

30 END 



100 IF ERR=71 THEN LOCATE 23,1: 

PRINT "DISK IS NOT READY" 
110 RESUME NEXT 
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ON-GOSUB and ON-GOTO 

Statements 



Purpose: Branches to one of several specified line numbers, 
depending on the value of an expression. 



Versions: 



Cassette 



Disk 



Advanced 



Compiler 

*** 



Format: ON n GOTO lineUine]... 

ON n GOSUB lineUine]... 
Remarks: 



line 



is a numeric expression, rounded to an 
integer, if necessary. It must be in the 
range to 255, or an Illegal function call error 
occurs. 

is the number of the line to which the 
program branches. 



The value of n determines which line number in the 
list the program uses for branching. For example, if 
the value of n is 3, the third line number in the list is 
the point at which the program branches. 

In the ON-GOSUB statement, each line number in 
the list must be the first line number of a subroutine. 
Eventually you must have a RETURN statement to 
bring you back to the line following the 
ON-GOSUB. 

If the value of n is 0, or greater than the number of 
items in the list (but less than or equal to 255), 
BASIC continues with the next executable 
statement. 
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ON-GOSUB and ON-GOTO 
Statements 

Example: The first example branches to line 150 if L-l equals 
1; to line 300 if L-l equals 2; to line 320 if L-l 
equals 3; and to line 390 if L-l equals 4. If L-l is 
equal to 0, or is greater than 4, then the program just 
goes on to the next statement. 

100 ON L-l GOTO 150,300,320,390 

The next example shows how to use an 
ON-GOSUB statement. 

100 REM display menu 



110 PRINT 

120 PRINT 

130 PRINT 

140 PRINT 

150 INPUT 



1. Routine 1" 

2. Routine 2" 

3. Routine 3" 

4. Routine 4" 
Your choice?" 



CHOICE 



160 ON CHOICE GOSUB 200, 300, 400,500 

170 GOTO 100 ' redisplay menu after routine is done 

200 REM start of first routine 



290 RETURN 

300 REM start of second routine 
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Purpose: 



ON KE Y(n) 
Statement 



Sets up a line number for BASIC to trap to when the 
specified function key or cursor control key is 
pressed. 



Versions: Cassette Disk 



Format: 
Remarks: 



Advanced Compiler 



ON KEY(«) GOSUB line 



n is a numeric expression in the range 1 to 

20 indicating the key to be trapped, as 
follows: 

1-10 Function keys Fl to F10 

1 1 Cursor Up 

12 Cursor Left 

13 Cursor Right 

14 Cursor Down 

15-20 keys defined by the form: 

KEY n,CHR$(KBflag) + CHR$(scan code). 
(Keys 15-20 can be trapped only in 
Advanced BASIC 2.0 and later releases.) 
See "KEY(n) Statement" for more 
information. 

line is the line number of the beginning of the 

trapping routine for the specified key. Setting 
line equal to stops trapping of the key. 

A KEY(n) ON statement must be executed to 
activate this statement. After KEY(n) ON, if a 
nonzero line number is specified in the ON KEY(n) 
statement, then every time the program starts a new 
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ON KEY(n) 
Statement 



statement, BASIC checks to see if the specified key 
was pressed. If so, BASIC performs a GOSUB to 
the specified line. 

If a KEY(«) OFF statement is executed, no trapping 
takes place for the specified key. Even if the key is 
pressed, the event is not remembered. 

If a KEY(«) STOP statement is executed, no 
trapping takes place for the specified key. However, 
if the key is pressed the event is remembered, so an 
immediate trap takes place when KEY(«) ON is 
executed. 

When the trap occurs, ah automatic KEY(n) STOP is 
executed so that recursive traps never take place. 
The RETURN from the trap routine automatically 
does a KEY(«) ON unless an explicit KEY(«) OFF 
was performed inside the trap routine. 

Event trapping does not take place when BASIC is 
not executing a program. When an error trap 
(resulting from an ON ERROR statement) takes 
place, all trapping is automatically disabled 
(including ON COM, ON ERROR, ON PEN, ON 
PLAY, ON STFtlG, 2nd ON TIMER). 

Key trapping may not work if you press other keys 
before the specified key. The key that caused the 
trap cannot be tested using INPUTS or INKEY$, so 
the trap routine for each key must be different if a 
different functiori is desired. 

You can use RETURN line if you want to go back to 
the BASIC program at a fixed line number. This 
nonlocal return must be used with care, however, 
since any other GOSUBs, WHILEs, or FORs active 
at the time of the trap remain active. 
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ON KEY(n) 
Statement 

Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. This 
ensures that every iteration of a FOR has a 
corresponding NEXT and every iteration of a 
WHILE has a corresponding WEND. 

KEY(/?) ON has no effect on whether the soft key 
values are displayed at the bottom of the screen. 

Special considerations for DOS national diskettes: 

The DOS national diskette keyboard programs have 
a feature that allows you to change between the 
United States and national keyboard at any time. Use 
the F 1 or F2 key while holding down Alt and Ctrl to 
perform the switch. (See Disk Operating System 
Reference for more information on the DOS 
keyboard programs.) If your BASIC program traps 
either of these keys, it will not pass the information 
to the DOS keyboard program and the keyboard 
change will not take place. If your program needs to 
provide this ability to change keyboard formats, 
avoid trapping the Fl and F2 keys. 

Note: The shift state you use when trapping 
either of these keys makes no difference when 
considering the DOS keyboard programs. Any 
shift of base state trapping of Fl and F2 prevents 
the keystroke from being passed to the DOS 
program. 
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ON KEY(n) 
Statement 

Example: The following is an example of a trap routine for 
function key 5. 

100 ON KEY(5) GOSUB 200 



200 'function key 5 pressed 



290 RETURN 140 

This example traps Ctrl-Break and Ctrl-Alt-Del. 
(For BASIC 2.0 and later releases.) 

10 KEY 15,CHR$(&H04)+CHR$(70) 'Trap Ctrl-Break 
20 KEY 16,CHR$(&H04+&H08)+CHR$(83) 

'Trap Ctrl-Alt-Del 
30 ON KEY(15) GOSUB 1000 
40 ON KEYU6) GOSUB 2000 
50 KEY(15) ON: KEY(16) ON 



1000 PRINT "Trapping for Ctrl -Break" 

1010 RETURN 

2000 TRAPS=TRAPS+1 

2010 ON TRAPS GOTO 2100,2200,2300,2400, 2500 

2020 ' 

2100 PRINT "First trap of System Reset" :RETURN 

2200 PRINT "Second trap of System Reset" :RETURN 

2300 PRINT "Third trap of System Reset" : RETURN 

2400 PRINT "Fourth trap of System Reset" : RETURN 

2500 KEY(16) OFF 'Disable trap of System Reset 
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Purpose: 

Versions: 

Format: 
Remarks: 



ON PEN 
Statement 



Sets up a line number for BASIC to transfer control 
to when the light pen is activated. 

Cassette Disk Advanced Compiler 
ON PEN GOSUB line 



line is the line number of the beginning of the trap 
routine for the light pen. Using a line number 
of disables trapping of the light pen. 

A PEN ON statement must be executed to activate 
this statement. After PEN ON, if a nonzero line 
number is specified in the ON PEN statement, then 
every time the program starts a new statement 
BASIC checks to see if the pen was activated. If so, 
BASIC performs a GOSUB line. 

If PEN OFF is executed, no trapping takes place. 
Even if the light pen is activated, the event is not 
remembered. 

If a PEN STOP statement is executed, no trapping 
takes place, but pen activity is remembered so that 
an immediate trap takes place when PEN ON is 
executed. 

When the trap occurs, an automatic PEN STOP is 
executed so recursive traps never take place. The 
RETURN from the trap routine automatically does a 
PEN ON unless an explicit PEN OFF was performed 
inside the trap routine. 
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ON PEN 

Statement 

Event trapping does not take place when BASIC is 
not executing a program. When an error trap 
(resulting from an ON ERROR statement) takes 
place all trapping is automatically disabled (including 
ON COM, ON ERROR, ON PEN, ON PLAY, ON 
STRIG, and ON TIMER) . 

PEN(0) is not set when pen activity causes a trap. 

You can use RETURN line if you want to go back to 
the BASIC program at a fixed line number. This 
nonlocal return must be used with care, however, 
since any other GOSUBs, WHILEs, or FORs active 
at the time of the trap remain active. 

Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. This 
insures that every iteration of a FOR has a 
corresponding NEXT and every iteration of a 
WHILE has a corresponding WEND. 

Note: Do not perform cassette I/O while PEN is 
ON. 

Example: This example sets up a trap routine for the light pen. 

10 ON PEN GOSUB 500 
20 PEN ON 



500 'subroutine for pen 



650 RETURN 30 
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ON PLAY(n) 

Statement 



Purpose: Plays continuous background music during program 
execution. (For BASIC 2.0 and later releases.) 



Versions: Cassette Disk 



Advanced Compiler 
*** 



Format: ON PLAY(«) GOSUB line 
Remarks: 



line 



is an integer expression in the range 1 to 32 
indicating the notes to be trapped. Values 
entered outside this range result in an Illegal 
function call error. 

is the beginning line number of the trap 
routine for PLAY. A line number of stops 
the trapping of PLAY. 



A PLAY ON statement must be used to start the ON 
PLAY(n) statement. After PLAY ON, if a nonzero 
line number is specified in the PLAY(«) statement, 
each time the program starts a new statement BASIC 
checks to see if the music buffer has gone from n to 
n-l notes. If so, BASIC performs a GOSUB to the 
specified line. 

If PLAY OFF is used, no trapping takes place. Even 
if a play activity takes place, the event is not 
remembered. 

If a PLAY STOP statement is used, no trapping 
takes place, but play activity is remembered so that 
an immediate trap takes place when PLAY ON is 
executed. 
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ON PLAY(n) 

Statement 



When the trap occurs, an automatic PLAY STOP is 
run so recursive traps never take place. The 
RETURN from the trap routine automatically does a 
PLAY ON unless an explicit PLAY OFF was 
performed inside the trap routine. 

Event trapping does not take place when BASIC is 
not running a program. When an error trap 
(resulting from an ON ERROR statement) takes 
place, all trapping is automatically disabled 
(including ON COM, ON ERROR, ON PEN, ON 
PLAY, ON STRIG, and ON TIMER). 

You can use RETURN line if you want to go back to 
the BASIC program at a fixed line number. This 
nonlocal return must be used with care, however, 
since any other GOSUBs, WHILEs, or FORs active 
at the time of the trap remain active. 

Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. 

Notes: 

1 . A PLAY event trap is issued only when PLAY is 
in the Music Background mode (PLAY "MB..."). 
An event trap is not issued when PLAY is in the 
Music Foreground mode (PLAY "MF..."). 

2. A PLAY event trap is not issued if the Music 
Background buffer is already empty when a 
PLAY ON statement is performed. 

3. Be careful choosing values for n. For example: 
ON PLAY(32) causes so many event traps that 
little time remains to run the rest of the program. 
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ON PLAY(n) 
Statement 



See also "PLAY(n) Function" in this chapter for 
additional information. 

Example: This example sets up a trap routine that is invoked 
when five notes are left in the background music 
buffer. 

10 ON PLAY(5) GOSUB 500 
20 PLAY ON 



500 'subroutine for background music 



650 RETURN 30 
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ON STRIG(n) 
Statement 



Purpose: Sets up a line number for BASIC to trap to when one 
of the joystick buttons (triggers) is pressed. 



Versions: Cassette Disk 



Format: 
Remarks: 



Advanced Compiler 



ON STRIG(rt) GOSUB line 



n can be 0, 2, 4, or 6, and indicates the button 

to be trapped as follows: 

button Al 

2 button Bl 

4 button A2 

6 button B2 

line is the line number of the beginning of the trap 
routine for STRIG. A line number of stops 
trapping of the joystick button. 

A STRIG(rt) ON statement must be executed to 
activate this statement for button n. If STRIG(«) ON 
is executed and a nonzero line number is specified in 
the ON STRIG (n) statement, then every time the 
program starts a new statement BASIC checks to see 
if the specified button has been pressed. If so, 
BASIC performs a GOSUB to the specified line. 

If STRIG(w) OFF is executed, no trapping takes 
place for button n. Even if the button is pressed, the 
event is not remembered. 
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ON STRIG(n) 
Statement 

If a STRIG(«) STOP statement is executed, no 
trapping takes place for button n, but the button 
being pressed is remembered so that an immediate 
trap takes place when STRIG(«) ON is executed. 

When the trap occurs, an automatic STRIG(rc) STOP 
is executed so that recursive traps never take place. 
The RETURN from the trap routine automatically 
does a STRIG(«) ON unless an explicit STRIG(n) 
OFF was performed inside the trap routine. 

Event trapping does not take place when BASIC is 
not executing a program. When an error trap 
(resulting from an ON ERROR statement) takes 
place, all trapping is automatically disabled 
(including ON COM, ON ERROR, ON PEN, ON 
PLAY, ON STRIG, and ON TIMER). 

Using STRIG(«) ON activates the interrupt routine 
that checks the button status for the specified 
joystick button. Downstrokes that cause trapping do 
not set functions STRIG(0), STRIG(2), STRIG(4), 
or STRIG(6). 

You can use RETURN line to go back to the BASIC 
program at a fixed line number. This nonlocal return 
must be used with care, however, since any other 
GOSUBs, WHILES, or FORs active at the time of 
the trap remain active. 

Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. This 
insures that every iteration of a FOR has a 
corresponding NEXT and every iteration of a 
WHILE has a corresponding WEND. 
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ON STRIG(n) 
Statement 

Example: This is an example of a trapping routine for the 
button on the first joystick. 

10 ON STRIGC0) GOSUB 2000 
20 STRIG(0) ON 



500 'subroutine for 1st button 



650 RETURN 
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ON TIMER 

Statement 



Purpose: Transfers control to a given line number in a BASIC 
program when a defined period of time has elapsed. 
(For BASIC 2.0 and later releases.) 



Versions: Cassette Disk 



Advanced Compiler 

*** 



Format: ON TIMER(«) GOSUB line 
Remarks: 



line 



is a numeric expression in the range 1 to 
86,400 (1 second through 24 hours). Values 
entered that are outside this range result in an 
Illegal function call error. 

is the beginning line number of the trap 
routine for TIMER. A line number of stops 
timer trapping. 



A TIMER ON statement must be used to start the 
ON TIMER statement. After TIMER ON, 
specifying a nonzero line number in the ON 
TIMER(n) statement causes BASIC to keep track of 
the passing seconds. When n seconds have elapsed, 
BASIC performs a GOSUB to the specified line. 
The event trap occurs, and BASIC starts counting 
again from 0. 

If TIMER OFF is used, no trapping takes place. 
Even if TIMER activity takes place, the event is not 
remembered. 
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ON TIMER 

Statement 



If a TIMER STOP statement is used, no trapping 
takes place, but TIMER activity is remembered so 
that an immediate trap occurs when TIMER ON is 
used. 

When the trap occurs, an automatic TIMER STOP is 
executed so that recursive traps never take place. 
The RETURN from the trap routine automatically 
does a TIMER ON unless an explicit TIMER OFF 
was performed inside the trap routine. 

Event trapping does not take place when BASIC is 
not running a program. When an error trap 
(resulting from an ON ERROR statement) takes 
place, all trapping is automatically disabled 
(including ON COM, ON ERROR, ON PEN, ON 
PLAY, ON STRIG, and ON TIMER). 

You can use RETURN line to go back to the BASIC 
program at a fixed line number. This nonlocal return 
must be used with care, however, since any other 
GOSUBs, WHILEs, or FORs active at the time of 
the trap remain active. 

Active loops are exited by setting the loop counter 
variable out of range or setting a conditional 
statement within the loop to terminate it. This 
insures that every iteration of a FOR has a 
corresponding NEXT and every iteration of a 
WHILE has a corresponding WEND. 
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ON TIMER 

Statement 

Example: ON TIMER is useful in programs that need an 

interval timer. This example displays the time of day 
on line 1 every minute. 

10 CLS 

20 ON TIMER(60) GOSUB 1 

30 TIMER ON 



10000 0LDR0W=CSRLIN 'save current row 

10010 OLDCOL=POS(0) 'save current column 

10020 LOCATE 1,1:PRINT TIMES; 

10030 LOCATE 0LDR0W,0LDC0L 'restore row & col 

10040 RETURN 
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OPEN 

Statement 

Purpose: Allows input or output to a file or device. 



Versions: Cassette 

*** 

Format: First form: 



Disk Advanced Compiler 

*** *** /**") 



Remarks: 



OPEN filespec [FOR mode] AS [#]filenum 
[LEN =recf] 

Alternate form: 

OPEN mode2, [#]filenum, filespec [,recl\ 

mode (first form) is one of the following: 

OUTPUT specifies sequential output mode. 

INPUT specifies sequential input mode. 

APPEND specifies sequential output mode where 

the file is positioned to the end of data on 
the file when it is opened. 

Note that mode must be a string constant, 
not enclosed in quotation marks. If mode 
is omitted, random access is assumed. 

mode2 (alternate form) is a string expression with 
the first character being one of the 
following: 
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OPEN 

Statement 

specifies sequential output mode 

1 specifies sequential input mode 

R specifies random input/output mode 

For both formats: 

filenum is an integer expression whose value is 
between 1 and the maximum number of 
files allowed. In Cassette BASIC, the 
maximum number is 4. In Disk BASIC 
and Advanced BASIC, the default 
maximum is 3, but this can be changed 
with the /F: switch on the BASIC 
command line. 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. Filespec 
must conform to the rules outlined under 
"Naming Files" in Chapter 3 of the 
BASIC Handbook; otherwise, an error 
occurs. 

reel is an integer expression which, if included, 

sets the record length for random files. It 
can range from 1 to 32767. The default 
record length is 128 bytes, reel cannot 
exceed the value set by the /S: switch in 
the BASIC command line. 

OPEN allocates a buffer for I/O to the file or device 
and determines the mode of access that is used with 
the buffer. 

filenum is the number that is associated with the file 
or device for as long as it is open and is used by 
other I/O statements to refer to the file or device. 
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OPEN 

Statement 



An OPEN must be executed before any I/O can be 
done to a device or file using any of the following 
statements, or any statement or function requiring a 
file number: 

PRINT # WRITE # 

PRINT # USING INPUTS 

INPUT # GET # 

LINE INPUT # PUT # 
IOCTL # 

GET and PUT are valid for random files or 
communications files. A disk file cay be either 
random or sequential, and a printer can be opened in 
either random or sequential mode; however, all other 
standard devices can be opened only for sequential 
operations. See "OPEN "COM... Statement." 

BASIC normally adds a line feed after each carriage 
return (CHR$(13)) sent to a printer. However, if 
you open a printer (LPT 1:, LPT2:, or LPT3:) as a 
random file with width 255, this line feed is 
suppressed. 

APPEND is valid only for disk files. The file pointer 
is initially set to the end of the file, and the record 
number is set to the last record of the file. PRINT # 
or WRITE # then extends the file. 

A file cannot be opened for sequential output or 
append if the file is already open. 

If the device name is omitted when you are using 
Cassette BASIC, CAS1: is assumed. If you are using 
Disk BASIC or Advanced BASIC, the DOS default 
drive is assumed. 
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OPEN 

Statement 

If CASl: is specified as the device and the filename 
is omitted, then the next data file on the cassette is 
opened. 

In Cassette BASIC, a maximum of four files can be 
open at one time (cassette, printer, keyboard, and 
screen). Note that only one cassette file can be open 
at a time. For Disk BASIC and Advanced BASIC 
the default maximum is three files. You can override 
this value by using the /F: option in the BASIC 
command line. 

If a file opened for input does not exist, a File not 
found error occurs. If a file that does not exist is 
opened for output, append, or random access, a file 
is created. 

Any values given outside the ranges indicated result 
in an Illegal function call error. The file is not 
opened. 

See also the section on device drivers in Chapter 3 of 
the BASIC Handbook, as well as Appendix A of the 
BASIC Handbook, for a complete explanation of 
using disk files. See also "OPEN "COM Statement" 
for information on opening communications files. 

Examples: Either of the following statements opens the file 

named "DATA" for sequential output on the default 
device (CASl: for Cassette BASIC, default drive for 
Disk BASIC and Advanced BASIC). 

10 OPEN "DATA" FOR OUTPUT AS #1 

or 
10 OPEN "0",#1,"DATA" 
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OPEN 

Statement 



In the preceding example, note that opening for 
output destroys any existing data in the file. If you 
do not wish to destroy data, you must open for 
APPEND. 

Either of the following two statements opens the file 
named "SSFILE" on the disk in drive B for random 
input and output. The record length is 256. 

10 OPEN "B:SSFILE" AS 1 LEN=256 

or 
10 OPEN "R",1,"B:SSFILE",256 

This example opens the file "DATA. ART" on the 
disk in drive A and positions the file pointers so that 
any output to the file is placed at the end of existing 
data in the file. 

10 FILES = "A:DATA.ART" 

20 OPEN FILES FOR APPEND AS 3 

Line 1 in the next example opens the printer in 
random mode. Because the default width is 80, the 
lines printed by lines 20 and 30 end with a carriage 
return/line feed. Line 40 changes the printer width 
to 255, so the line feed after the carriage return is 
suppressed. Therefore, the line printed by line 
50 ends only with a carriage return and not a line 
feed. This causes the line printed by line 70 to 
overprint "This line will be underlined", causing the 
line to be underlined. Line 60 changes the width 
back to 80 so the underlines and following lines end 
with a line feed. 
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OPEN 

Statement 

10 OPEN "LPT1:" AS #1 

20 PRINT #1, "Printing width 80" 

30 PRINT #l,"Now change to width 255" 

40 WIDTH #1,255 

50 PRINT #l,"This line will be underlined" 

60 WIDTH #1,80 

70 PRINT #1, STRING$(28,"_") 

80 PRINT #1, "Printing width 80 with CR/LF" 

RUN 

Printing width 80 
Now change to width 255 
This line will be underlined 
Printing width 80 with CR/LF 

The following examples illustrate the use of paths 
for filespec. 

Either of these statements opens the file called 
"DATA" for sequential output on the default device 
in the directory called LVL2. 

10 OPEN "LVL1\LVL2\DATA" FOR OUTPUT AS #1 

or 
10 OPEN "0",#1,"LVL1\LVL2\DATA" 

Either of the next two statements opens the file 
named "RRFILE" in the LVL1 directory on the disk 
in drive B for random input and output. The record 
length is 256. 

20 OPEN "B:LVL1\RRFILE" AS 1 LEN=256 

or 

20 OPEN "R",B:LVL1\RRFILE:",256 
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OPEN "COM. . . 

Statement 



Purpose: 
Versions: 



Format: 



Remarks: 



Opens a communications file. 
Cassette 



Disk 

*** 



Advanced 

*** 



Compiler 



Valid only with Asynchronous Communications 
Adapter. 

OPEN "COMn:[speed\ Lparity] [,data] [,stop] [,RS] 
[,CS[/i]] [,DS[«]] [,CD[/i]] [,LF] [,PE]" AS 
[#]filenum [LEN=number] 



n is 1 or 2, indicating the number of the 

Asynchronous Communications Adapter. 

speed is an integer constant specifying the 

transmit/receive bit rate in bits per second 
(bps). Valid speeds are 75, 110, 150, 
300, 600, 1200, 1800, 2400, 4800, and 
9600. The default is 300 bps. 

parity is a one-character constant specifying the 
parity for transmit and receive as follows: 

S SPACE: Parity bit always transmitted and 
received as a space (0 bit). 

O ODD: Odd transmit parity; odd receive parity 
checking. 

M MARK: Parity bit always transmitted and 
received as a mark (1 bit). 
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OPEN "COM... 

Statement 

E EVEN: Even transmit parity; even receive 
parity checking. 

N NONE: No transmit parity; no receive parity 
checking. 

The default is EVEN (E). 

data is an integer constant indicating the 

number of transmit/receive data bits. 
Valid values are: 5, 6, 7, or 8. The 
default is 7. 

stop is an integer constant indicating the 

number of stop bits. Valid values are 1 
or 2. The default is two stop bits for 75 
and 110 bps; one stop bit for all others. 
If you use 5 for data, a 2 here means 
1-1/2 stop bits. 

filenum is an integer expression that evaluates to 
a valid file number. The number is then 
associated with the file for as long as it is 
open and is used by other 
communications I/O statements to refer 
to the file. 

number is the maximum number of bytes that can 
be read from the communication buffer 
when using GET or PUT. The default is 
128 bytes. 

OPEN "COM., allocates a buffer for I/O in the 
same fashion as OPEN for disk files. It supports 
RS232 asynchronous communication with other 
computers and peripherals. 

A communications device can be open to only one 
file number at a time. 
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OPEN "COM. . . 

Statement 



The RS, CS, DS, CD, LF and PE options affect the 
line signals as follows: 

RS suppresses RTS (Request To Send) 

CS[n] controls CTS (Clear To Send) 

DS[n] controls DSR (Data Set Ready) 

CD[n] controls CD (Carrier Detect) 

LF sends a line feed following each carriage 

return 

PE enables parity checking 

The CD (Carrier Detect) is also known as the RLSD 
(Received Line Signal Detect). 

Note: The speed, parity, data, and stop parameters 
are positional, but RS, CS, DS, CD, LF, and PE 

are not. 

The RTS (Request To Send) line is turned on when 
you execute an OPEN "COM., statement unless you 
include the RS option. 

The n argument in the CS, DS, and CD options 
specifies the number of milliseconds to wait for the 
signal before returning a Device timeout error, n can 
range from to 65535. If n is omitted or is equal to 
zero, then the line status is not checked at all. 

The defaults are CS1000, DS1000, and CD0. If RS 

was specified, CS0 is the default. 

That is, normally I/O statements to a 
communications file fail if the CTS (Clear To Send) 
or DSR (Data Set Ready) signals are off. The 
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OPEN "COM. . . 

Statement 

system waits 1 second before returning a Device 
timeout. The CS and DS options allow you to ignore 
these lines or to specify the amount of time to wait 
before the timeout. 

Normally Carrier Detect (CD or RLSD) is ignored 
when an OPEN "COM... statement is executed. The 
CD option allows you to test this line by including 
the n parameter, in the same way as CS and DS. If n 
is omitted or is equal to zero, then Carrier Detect is 
not checked at all (which is the same as omitting the 
CD option). 

The LF parameter is intended for those using 
communications files to print to a serial line printer. 
When you specify LF, a line feed character (hex0A) 
is automatically sent after each carriage return 
character (hex 0C). (This includes the carriage 
return sent as a result of the width setting.) INPUT 
# and LINE INPUT #, when used to read from a 
communications file that was opened with the LF 
option, stop when they see a carriage return. The 
line feed is always ignored. 

The PE option enables parity checking. The default 
is no parity checking. The PE option causes a Device 
I/O error on parity errors and turns on the high 
order bit for 7 or less data bits. The PE option does 
not affect framing and overrun errors. These errors 
always turn on the high order bit and cause a Device 
I/O error. 

Any coding errors within the string expression 
starting with speed result in a Bad file name error. No 
indication is given as to which parameter is in error. 
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Statement 

See also Appendix C, "Communications," for more 
information on control of output signals, as well as 
other technical information on communications 
support. 

If you specify 8 data bits, you must specify parity N. 
BASIC uses all 8 bits in a byte to store numbers, so 
if you are transmitting or receiving numeric data (for 
example, by using PUT), you must specify 8 data 
bits. (This is not necessary if you are sending 
numeric data as text.) 

See also the previous entry, "OPEN Statement," for 
information on opening devices other than 
communications devices. 

Example: In this example, file 1 is opened for communication 
with all defaults. The speed is 300 bps with even 
parity. There are 7 data bits and 1 stop bit. 

10 OPEN "C0M1:" AS #1 

In this example, file 2 is opened for asynchronous 
I/O at 1200; no parity is to be produced or checked; 
8-bit bytes are sent and received; and 1 stop bit is 
transmitted. 

10 OPEN "COM2:1200,N,8" AS #1 

This example opens COM1: at 9600 bps with no 
parity and 8 data bits. CTS, DSR, and CD are not 
checked. 

10 OPEN "COM1:9600,N,8,,CS,DS,CD" AS #1 

This example opens COM1: at 1200 bps with the 
defaults of even parity, 7 data bits, and 1 stop bit. 
RTS is sent, CTS is not checked, and Device timeout 
is given if DSR is not seen within 2 seconds. The 
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Statement 

commas are required to indicate the position of the 
parity, start, and stop parameters, even though a value 
is not specified. This is what is meant by positional 
parameters. 

10 OPEN "COM1:1200,,,,CS,DS2000" AS #1 

An OPEN statement can be used with an ON 
ERROR statement to make sure a modem is working 
properly before sending any data. For example, the 
following program makes sure you get Carrier Detect 
(CD or RLSD) from the modem before starting. 
Line 20 | is set to timeout after 10 seconds. TRIES 
is set to 6 so we give up if Carrier Detect is not seen 
within 1 minute. Once communication is established, 
the file reopens with a shorter delay until timeout. 

10 TRIES=6:0N ERROR GOTO 100 

20 OPEN "COM1:300,N,8,2,CS,DS,CD10000" AS #1 

30 ON ERROR GOTO 

40 CLOSE #1 'Works so can continue 

50 GOTO 1( 



100 TRIES=TRIES-1 

110 IF TRIES=0 THEN ON ERROR GOTO 'give up 

120 RESUME 



1000 OPEN "COM1:300,N,8,2,CS,DS,CD2000" AS #1 
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OPEN "COM... 

Statement 



The next example shows a typical way to use a 
communication file to control a serial line printer. 
The LF parameter in the OPEN statement ensures 
that lines do not print on top of each other. 



10 WIDTH "C0M1:", 132 
20 OPEN "COM1:1200,N,8,,CS1 
DS10000,CD10000,LF" AS #1 
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OPTION BASE 

Statement 



Purpose: Declares the minimum value for array subscripts. 
Versions: Cassette Disk Advanced Compiler 



Format: OPTION BASE n 
Remarks: n is 1 or 0. 

The default base is 0. If the statement: 

OPTION BASE 1 

is executed, the lowest value an array subscript can 
have is 1. 

The OPTION BASE statement must be coded before 
you define or use any arrays. An error occurs if you 
change the base value when arrays exist. 

In BASIC 1.10, the program you are chaining to 
cannot have an OPTION BASE statement even 
when both programs have the same base value. 
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OUT 
Statement 



Purpose: Sends a byte to a machine output port. 



Versions: 



Cassette 
*** 



Disk 



Advanced 

*** 



Compiler 

*** 



Format: 
Remarks: 



OUT n,m 



m 



is a numeric expression for the port number, 
in the range to 65535. 

is a numeric expression for the data to be 
transmitted, in the range to 255. 



See also the IBM Personal Computer Technical 
Reference manual for a description of valid port 
numbers (I/O addresses). 

OUT is the complementary statement to the INP 
function. See also "INP Function." 

One use of OUT is to affect the video output. On 
some displays attached to the Color/Graphics 
Monitor Adapter, you may find that the first two or 
three characters on the line don't show up on the 
screen. If your display does not have a horizontal 
adjustment control, you can use the following 
statements to shift the display: 
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Statement 

OUT 980,2: OUT 981,43 

This shifts the display two characters to the right in 
40-column width (or 16 points in medium resolution 
graphics mode, or 32 points in high resolution 
graphics mode). 

OUT 980,2: OUT 981,85 

This shifts the display five characters to the right in 
80-column width. 

The shift caused by these OUT statements remains in 
effect until a WIDTH or SCREEN statement is 
executed. The MODE command from DOS can also 
be used to shift the display as described here; it has 
the benefit of remaining in effect until a System 
Reset. 

Example: This sends the value 100 to output port 32. 

100 OUT 32,100 
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PAINT 

Statement 

Purpose: Fills in an area on the screen with the selected color. 

Versions: Cassette Disk Advanced Compiler 

*** (**\ 

Graphics mode only. 

Format: PAINT {x,y) [[,paint] [,boundary\ ^background]] 

Remarks: 

(x,y) are the coordinates of a point within the 

area to be filled in. The coordinates can 
be given in absolute or relative form 
(see "Specifying Coordinates" under 
"Graphics Modes" in Chapter 3 of the 
BASIC Handbook). This point is used 
as a starting point. Points specified 
outside the limits of the screen are not 
plotted, and no error occurs. 

paint can be a numeric or string expression. 

It is used to fill a color or pattern in or 
around a bounded area. When paint is a 
numeric expression, it chooses an 
attribute from the legal attribute range 
for the current screen mode. In medium 
resolution, the color is the current color 
for that attribute defined by the 
COLOR statement. Four attributes 
(0-3) are available in medium 
resolution. In high resolution, two 
attributes (0-1) are available. Zero is 
always the attribute for the background. 
The default foreground attribute is the 
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boundary 



background 



PAINT 

Statement 

maximum attribute for that screen 
mode: 3 in medium resolution; 1 in high 
resolution. 

If paint is a string expression, then 
"tiling" is performed, as described later 
in this entry. Paint tiling is valid for 
BASIC 2.0 and later releases. 

is a numeric expression that evaluates to 
an integer in the legal attribute range of 
the current screen mode. It defines the 
attribute for the edges of the figure to 
be painted. 



is a 1 -byte string expression used in 
paint tiling. (For BASIC 2.0 and later 
releases.) 



Since there are only two attributes in high resolution, 
paint should not be different from boundary. By 
default, boundary is equal to paint. You can paint 
either a white area black or a black area white. 

In medium resolution, you can fill inside or around a 
defined area with any one of four colors from the 
current palette defined by the COLOR statement. 
An example of this is filling a red circle with green, 
or surrounding a red circle with green. 

paint begins at the specified starting point and covers 
an area until it meets the specified boundary 
attribute. Therefore, paint must always begin inside 
the area to be painted. If the specified starting point 
already has the same attribute as boundary, then 
painting stops at that point and appears not to occur. 
An example of this is plotting a point with PSET that 
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PAINT 

Statement 



has the same attribute as boundary, and then using 
the coordinates of that point with the PAINT 
statement. 

PAINT fills any designated area no matter what the 
shape of the area; however, the more complex the 
edges of a figure (jagged edges, for instance), the 
more stack space BASIC uses. Under these 
circumstances you may want to use the CLEAR 
statement at the beginning of your program to 
increase the stack space. 

The PAINT statement allows scenes to be displayed 
with very few statements. 

In the example that follows, the PAINT statement in 
line 30 fills in the box drawn in line 20 with the 
color represented by the attribute in the current 
palette. 

10 SCREEN 1 

20 LINE (0,0)-(100,150),2,B 

30 PAINT (50, 50), 1,2 

The following discussion deals with paint tiling only. 
(For BASIC 2.0 and later releases.) 

To use paint tiling, the paint attribute must be a 
string expression in the form: 

CHR$(&Hnn)+CHR$(&Hnn)+CHR$(&Hnn) 

The CHR$ sequence specifies a bit mask that is 1 
byte wide. When the mask is plotted all the way 
across and down the designated area defined by 
boundary, a pattern is created rather than a solid 
color. You design the pattern. The two hexadecimal 
numbers in the CHR$ expression correspond to 8 
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bits, or 1 byte. The string expression can contain up 
to 64 bytes. The design created by the string 
expression can be mapped as follows: 

x increases — > 
7 65 43 2 10 

0,0 xxxxxxxx Tile byte 

0,1 xxxxxxxx Tile byte 1 

0,2 xxxxxxxx Tile byte 2 



0,63 xxxxxxxx Tile byte 63 

(maximum allowed) 

The tile pattern is repeated uniformly over the area 
defined by boundary. If you do not define an area, 
the whole screen is your designated area. Each byte 
of the tile string masks 8 bits along the x axis when 
plotting points. Each byte of the tile string is rotated 
as required to align the pattern along the y axis. 
BASIC chooses the particular byte of the pattern to 
plot, using the formula y mod tile length. 
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Because there is only 1 bit per pixel in high 
resolution, a point is plotted at every position in the 
bit mask that has a value of 1 . In high resolution, the 
screen can be painted with x's using the following 
example: 

10 CLS:SCREEN 1: COLOR 1: KEY OFF 

20 LOCATE 12,7:PRINT "I JUST LOVE MY IBM COMPUTEF 

30 PAINT(320,100) ,CHR$(&H81)+CHR$(&H42)+ 

CHR$(&H24)+CHR$(&H18)+CHR$(&H24)+ 

CHR$(&H24)+CHR$(&H42)+CHR$(&H81) 
40 GOTO 40 

The length of this mask is 8, indexed through 7. 
In this case, PAINT at coordinates (320,100) begins 
by plotting byte 4. This is calculated using the y mod 
tile length formula by substituting 1 00 for y and 8 for 
tile length. This pattern appears on the screen as: 

x increases — > 

Tile byte 10000001 CHR$(&H81) 

Tile byte 1 010 010 CHR$(&H42) 

Tile byte 2 10 010 CHR$(&H24) 

Tile byte 3 00011000 CHR$(&H18) 

Tile byte 4 000 11000 CHR$(&H18) 

Tile byte 5 010 010 CHR$(&H24) 

Tile byte 6 010 010 CHR$(&H42) 

Tile byte 7 10000001 CHR$(&H81) 
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The method of designing patterns in each screen 
varies depending on the number of color attributes 
available in each screen mode. This is so because the 
number of bits per pixel is directly related to the 
number of color attributes available in each screen 
mode. In any screen, where X is the total number of 
color attributes for that screen, 

LOG 2 (X)=Y 

where Y is the number of bits per pixel. In high 
resolution, each byte of the string is able to plot 8 
points across the screen (1 bit per pixel), since 
LOG 2 (2) = l. 

In Screen 1 , one medium-resolution tile byte 
describes 4 pixels, since medium resolution has only 
2 bits per pixel: that is, LOG 2 (4)=2 bits per pixel. 
Every 2 bits of the tile byte describes 1 of 4 possible 
color attributes associated with each of the 4 pixels 
to be plotted. 

The following chart shows the binary and 
hexadecimal values associated with each attribute in 
medium resolution. 
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Color 
palette 




Attrib. 

in 

binary 


Pattern to 
draw solid 
line in 
binary 


Pattern to 
draw solid 
line in 
hexadecimal 




green 

red 

brown 


01 
10 
11 


01010101 
10101010 
11111111 


&H55 

&HAA 

&HFF 














Color 

palette 

1 


Attrib. 

in 

binary 


Pattern to 
draw solid 
line in 
binary 


Pattern to 
draw solid 
line in 
hexadecimal 




cyan 

magenta 

white 


01 
10 
11 


01010101 
10101010 
11111111 


&H55 

&HAA 

&HFF 



In medium resolution, the following example plots a 
pattern of boxes with a border color of red in palette 
and magenta in palette 1. 

10 CLS: SCREEN 1: COLOR 1: KEY OFF 

20 LOCATE 12,7:PRINT "I JUST LOVE MY IBM COMPUTER" 

30 PAINT (320,100),CHR$(&HAA)+CHR$(&H82)+ 

CHR$(&H82)+CHR$(&H82)+CHR$(&H82)+ 

CHR$(&H82)+CHR$(&H82)+CHR$(&HAA) 
40 GOTO 40 
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76543210 

Tile byte 10101010 CHR$(&HAA) 

Tile byte 1 10 010 CHR$(&H82) 

Tile byte 2 10 010 CHR$(&H82) 

Tile byte 3 10 010 CHR$(&H82) 

Tile byte 4 10 010 CHR$(&H82) 

Tile byte 5 10 010 CHR$(&H82) 

Tile byte 6 10 010 CHR$(&H82) 

Tile byte 7 10101010 CHR$(&HAA) 

Occasionally, you may want to tile over an already 
painted area that is the same color or pattern as two 
consecutive bytes in the tile mask. Normally, this 
constitutes a terminating condition because your 
point is surrounded by points of the same bit pattern. 
(An example follows on the use of background.) 

You can use the background attribute to skip this 
terminating condition. You cannot specify more 
than two consecutive lines in the tile pattern that 
matches this background attribute. Doing so causes 
an Illegal function call error. 
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Example: The program below demonstrates how to tile an area 
with three lines of red, two lines of green, and one 
line of red. The palette then changes to show that 
the same tile mask yields the same pattern with 
different colors. 

10 CLS:SCREEN 1,0: KEY OFF 

20 TIL$=CHR$(&HAA)+CHR$(&HAA)+CHR$(&HAA) 

+CHR$(&H55)+CHR$(&H55)+CHR$(&HFF) 
30 COLOR 0,0 'choose palette 
40 VIEW (1,1)-(150,100),0,2 
50 GOSUB 1000 

60 COLOR 0,1 'choose palette 1 
70 GOTO 1020 

1000 PAINT (125, 50), TILS, 2 
1010 RETURN 
1020 GOTO 1020 
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The following example uses paint tiling with the 
background attribute. 

10 CLS:SCREEN 1: COLOR 0,1 : KEY OFF 

20 TIL$=CHR$(&H5F)+CHR$(&H5F)+CHR$(&H27)+CHR$(&H81) 

30 VIEW (1 ,1 )-( 150,100) ,0,2 

40 LOCATE 3,22:PRINT "<---without back-" 

50 LOCATE 4,22: PRINT " ground tile " 

60 PAINT (125,50) ,CHR$(&H5F) 

70 PAINT (125,50),TIL$,2 

80 ' 

90 'with background tile' 

100 ' 

110 VIEW (160,100)-(310,198),0,2 

120 LOCATE 16 ,1 :PRINT "With background-->" 

130 LOCATE 17 ,1 :PRINT "tile chr$(&H5F)" 

140 PAINT (125,50) ,CHR$(&H5F) 

150 PAINT (125 ,50) ,T I L$ , 2 , CHR$ ( &H5F) 

160 LINE (1 ,100)-(319 ,100) ,3 

170 FOR 1=1 TO 2500:NEXT I 

180 GOTO 180 
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Function 



Purpose: Returns the byte read from the indicated memory 
position. 

Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



Example: 



v = PEEK(h) 



n is an integer in the range to 65535. « is the 

offset from the current segment as defined by 
the DEF SEG statement. See "DEF SEG 
Statement." 

The returned value is an integer in the range to 

255. 

PEEK is the complementary function to the POKE 
statement. See "POKE Statement." 

The following example in a program tests which 
display adapter is on the system. After line 30 is 
executed, the variable IBMMONO has a value of 
if the IBM Color/Graphics Monitor Adapter is used, 
or 1 if the IBM Monochrome Display and Parallel 
Printer Adapter is used. 

10 'test display adapter 

20 DEF SEG=0 

30 IF (PEEK(&H410) AND &H30)=&H30 

THEN IBMM0N0=1 

ELSE IBMMONO=0 
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Purpose: Reads the light pen. 

Versions: Cassette Disk Advanced Compiler 

PEN STOP only in Advanced BASIC and Compiler. 
Format: As a statement: 
PEN ON 
PEN OFF 
PEN STOP 

As a function: 

v = PEN(rt) 

Remarks: The PEN function, v=PEN(«), reads the light pen 
coordinates. 



is a numeric expression in the range to 9, 
and affects the value returned by the function 
as follows: 

A flag indicating if pen was down since 

last poll. Returns - 1 if down, if not. 

1 Returns the x coordinate where pen 
was last activated. Range is to 319 
in medium resolution, and to 639 in 
high resolution. 
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2 Returns the y coordinate where pen 
was last activated. Range is to 199. 

3 Returns the current pen switch value. 
-1 if down, if up. 

4 Returns the last known valid x 
coordinate. Range is to 3 1 9 in 
medium resolution, and to 639 in 
high resolution. 

5 Returns the last known valid y 
coordinate. Range is to 199. 

6 Returns the character row position 
where pen was last activated. Range is 
1 to 24. 

7 Returns the character column position 
where pen was last activated. Range is 
1 to 40 or 1 to 80, depending on 
WIDTH. 

8 Returns the last known valid character 
row. Range is 1 to 24. 

9 Returns the last known valid character 
column position. Range is 1 to 40 or 1 
to 80, depending on WIDTH. 

PEN ON enables the PEN read function. The PEN 
function is initially off. A PEN ON statement must 
be executed before any pen read function calls can 
be made. A call to the PEN function while the PEN 
function is off results in an Illegal function call error. 

Conversely, to improve execution speed, turn the pen 
off with a PEN OFF statement when you are not 
using the light pen. 



248 



PEN 

Statement and Function 

For Advanced BASIC, executing PEN ON also 
allows trapping to take place with the ON PEN 
statement. After PEN ON, if a nonzero line number 
was specified in the ON PEN statement, then every 
time the program starts a new statement BASIC 
checks to see if the pen was activated. See "ON 
PEN Statement." 

PEN OFF disables the PEN read function. For 
Advanced BASIC, no trapping of the pen takes 
place. Action by the light pen is not remembered 
even if it does take place. 

PEN STOP is available only in Advanced BASIC. It 
disables trapping of light pen activity. If activity does 
occur, however, it is remembered, so an immediate 
trap occurs when a PEN ON is executed. 

When the pen is down in the border area of the 
screen, the values returned are inaccurate. 

You should not try I/O to cassette while PEN is ON. 

Example: This example prints the pen value since the last poll, 
and the current value. 

10 PEN ON 

20 FOR 1=1 TO 500 

30 X=PEN(0): X1=PEN(3) 

40 PRINT X, XI 

50 NEXT 

PEN OFF 
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Purpose: Plays music as specified by string. 

Versions: Cassette Disk Advanced Compiler 

Format: PLAY string 

Remarks: PLAY implements a concept similar to DRAW by 
imbedding a "tune definition language" into a 
character string. 

string is a string expression consisting of single- 
or double-character music commands. 

The commands in PLAY are: 

A to G with optional #, +, or - 

Plays the indicated note in the current octave. 
A number sign (#) or plus sign (+) afterward 
indicates a sharp; a minus sign (-) indicates a 
flat. A #, +, or - is not allowed unless it 
corresponds to a black key on a piano. For 
example, B# is an invalid note. 

O n Octave. Sets the current octave for the notes 
that follow. There are 7 octaves, numbered 
to 6. Each octave goes from C to B. Octave 
3 starts with middle C. Octave 4 is the 
default octave. 

> n Go up to the next higher octave and play note 
n. Each time note n is played, the octave goes 
up, until it reaches octave 6. For example, 
PLAY ">A" raises the octave and plays note 
A. Each time PLAY ">A" is executed, the 
octave goes up until it reaches octave 6; then 
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each time PLAY ">A" executes, note A 
plays at octave 6. (For BASIC 2.0 and later 
releases.) 

< n Go down one octave and play note n. Each 
time each time note n is played, the octave 
goes down, until it reaches octave 0. For 
example, PLAY "<A" lowers the octave and 
plays note A. Each time PLAY "<A" is 
executed, the octave goes down until it 
reaches octave 0; then each time PLAY 
"<A" executes, note A plays at octave 0. 
(For BASIC 2.0 and later releases.) 

N n Plays note n, which can range from to 84. 
In the 7 possible octaves, there are 84 notes. 
«=0 means "rest." This is an alternative way 
of selecting notes besides specifying the 
octave (O n) and the note name (A-G). 

L n Sets the length of the notes that follow. The 
actual length of the note is \/n. n can range 
from 1 to 64. 

Length Equivalent 



LI 


whole note 


L2 


half note 


L3 


one of a triplet of three half notes 




(1/3 of a 4-beat measure) 


L4 


quarter note 


L5 


one of a quintuplet 




(1/5 of a measure) 


L6 


one of a quarter-note triplet 



L64 sixty-fourth note 
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Pn 



Tn 



MF 



MB 



The length can also follow the note when you 
want to change only the length of the note. 
For example, A16 is equivalent to L16A. 

Pause (rest), n can range from 1 to 64, and 
figures the length of the pause in the same 
way as L (length). 

(dot or period) When placed after a note, 
causes the note to be played as a dotted note. 
A dot increases the duration of a note by half 
the duration of the note. A note can have 
more than one dot. Each dot increases the 
total value of the note by 1 /2 the value of the 
previous dot. For example, a double-dotted 
half note is equivalent in duration to a half 
note plus a quarter note plus an eighth note. 
Dots can also appear after a pause (P) to 
scale the pause length in the same way. 

Tempo. Sets the number of quarter notes in a 
minute, n can range from 32 to 255. The 
default is 120. Under "SOUND Statement" is 
a table listing common tempos and the 
equivalent beats per minute. 

Music foreground. Music (created by 
SOUND or PLAY) runs in foreground. Each 
subsequent note or sound will not start until 
the previous note or sound is finished. You 
can press Ctrl-Break to exit PLAY. Music 
foreground is the default state. 

Music background. Music (created by 
SOUND or PLAY) runs in background 
instead of in foreground. Each note or sound 
is placed in a buffer, allowing the BASIC 
program to continue executing while music 
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plays in the background. The music 
background buffer can hold up to 32 notes at 
one time. 

MN Music normal. Each note plays 7/8 of the 
time specified by L (length). This is the 
default setting of MN, ML, and MS. 

ML Music legato. Each note plays the full period 
set by L (length). 

MS Music staccato. Each note plays 3/4 of the 
time specified by L. 

X variable; 

Executes specified string. 

In all these commands the n argument can be a 
constant such as 12, or it can be = variable, where 
variable is the name of a variable. The semicolon (;) 
is required when you use a variable in this way, and 
when you use the X command. Otherwise a 
semicolon is optional between commands, except 
that a semicolon is not allowed after MF, MB, MN, 
ML, or MS. Also, any blanks in string are ignored. 

You can also specify variables in the form 
VARPTR$ {variable), instead of =variable;. The 
VARPTR$ form is the only one that can be used in 
compiled programs. For example: 

One Method Alternative Method 

PLAY "XA$;" PLAY "X"+VARPTR$(A$) 
= !;" PLAY "0 = " + VARPTR$(I) 
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You can use X to store a "subtune" in one string and 
call it repetitively with different tempos or octaves 
from another string. 

Examples: The following example plays a tune. 

10 'little lamb 

20 MARY$="GFE-FGGG" 

30 PLAY "MB T100 03 L8;XMARY$;P8 FFF4" 

40 PLAY "GB-B-4; XMARY$; GFFGFE-...." 

The following example plays the scale from octave 
to octave 6. 

10 ' Play the scale using > octave 

20 SCALE$="CDEFGAB" 

30 PLAY "00 XSCALE$;" 

40 FOR 1=1 TO 6 

50 PLAY ">XSCALE$;" 

60 NEXT 

70 ' Play the scale using < octave 

80 PLAY "06 XSCALE$;" 

90 FOR 1=1 TO 6 

100 PLAY "<XSCALE$;" 

110 NEXT 
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Function 



Purpose: Returns the number of notes currently in the music 
background buffer. (For BASIC 2.0 and later 
releases.) 



Versions: Cassette Disk 



Advanced Compiler 

*** 



Format: v=PLAY(n) 
Remarks: 



n is a dummy argument that can have any value. 

PLAY(n) returns a when the program is running in 
Music Foreground mode. The maximum value that 
can be returned is 32, which is the maximum number 
of notes held in the buffer. 

PLAY(n) returns notes in the buffer only when you 
are using Music Background (MB) mode. 



Example: 



10 'When 5 notes are left in the background music buffer 
20 'go to line 1000 and play another tune 
30 PLAY "MB CDEFGAB" 
40 IF PLAY(1)=5 GOTO H 
50 GOTO 2000 



1000 PLAY "MB 04 T200 L4 MS GG#GE" 
2000 END 
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Purpose: Maps physical coordinates to world coordinates or 
world coordinates to physical coordinates. (For 
BASIC 2.0 and later releases.) 



Versions: Cassette Disk 



Advanced Compiler 

*** 



Format: 
Remarks: 



Graphics mode only 
v=PMAP(x,n) 



x coordinate of the point that is to be 

mapped 

n can be a value in the range to 3 such 

that: 

maps the world coordinate x to 
the physical coordinate x 

1 maps the world coordinate y to 
the physical coordinate y 

2 maps the physical coordinate x to 
the world coordinate x 

3 maps the physical coordinate y to 
the world coordinate y 

PMAP is used to translate coordinates between the 
world system as defined by the WINDOW statement 
and the physical coordinate system. 
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PMAP(x,0) and PMAP(jc,1) are used to map values 
from the world coordinate system to the physical 
coordinate system. 

PMAP(jc,2) and PMAP(x,3) are used to map values 
from the physical coordinate system to the world 
coordinate system. 

For example, if the statement 
SCREEN 1: WINDOW (-1 ,-1 )-( 1 ,1 ) 

is in effect you can use PMAP to map the world 
coordinate points of (-1,-1) and (1,1) to their 
corresponding physical points on the screen. 

PMAP (-1,0) returns the physical x coordinate value 
of 0. 

PMAP(-1,1) returns the physical y coordinate value 
of 199. 

PMAP (1,0) returns the physical x coordinate value 
of 319. 

PMAP (1,1) returns the physical y coordinate value 
of 0. 

The above information tells you that the point 
(-1,-1), which is in the lower left corner of the 
screen, corresponds to the physical point (0,199). 
You also know that the point (1,1), which is in the 
upper right corner, corresponds to the physical point 
(319,0). 
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Purpose: The first form returns the attribute of the specified 
point on the screen. The second form returns the 
value of the current x or y graphics coordinate. 



Versions: Cassette Disk 



Advanced Compiler 



Format: 



Remarks: 



Graphics mode only, 
v = POINT (x,y) 
v = POINT (n) 



(x,y) are the coordinates of the point to be 

used. They must be in absolute form as 
explained in "Specifying Coordinates" 
under "Graphics Modes" in Chapter 3 of 
the BASIC Handbook. 

If the point given is out of range, the value 
-1 is returned. In medium resolution valid 
returns are 0, 1, 2, and 3. In high 
resolution they are and 1 . 

n returns the value of the current x or y 

graphics coordinate. (For BASIC 2.0 and 
later releases.) n can have a value from 
to 3 where: 







returns the current physical x 
coordinate. 

returns the current physical y 
coordinate. 



258 



POINT 

Function 

2 returns the current world x 
coordinate if WINDOW is 
active. If WINDOW is not 
active, returns the current 
physical x coordinate. 

3 returns the current world y 
coordinate if WINDOW is 
active. If WINDOW is not 
active, returns the current 
physical y. 

See also "WINDOW Statement." 

Example: The following example inverts the current setting of 
point (1,1). 

10 SCREEN 2 

20 IF POINT(I,I)<>0 THEN PRESET(I.I) 

ELSE PSET(I,I) 
or 
20 PSET(I,I),1-P0INT(I,I) 
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This example illustrates values returned by the 
POINT function. Note the change in the values 
depending upon WINDOW. 

10 CLS : SCREEN 1 ,0: KEY OFF 

20 PRINT "POINT(n) with WINDOW inactive" 

30 60SUB 110 

40 WINDOW (0,0)-(319,199) 

50 PRINT "POINT(n) with WINDOW active" 

60 GOSUB 110 

70 PRINT "POINT(n) with WINDOW and SCREEN active 1 

80 WINDOW SCREEN (0 ,0 ) - ( 319 , 199 ) 

90 GOSUB 110 

100 END 

110 PSET (5,15) 

120 FOR 1=0 TO 3 

130 PRINT POINT (I); 

140 NEXT 

150 PRINTrPRINT 

160 RETURN 

RUN 

POINT(n) with WINDOW inactive 

5 15 5 15 

POINT(n) with WINDOW active 

5 184 5 15 

POINT(n) with WINDOW and SCREEN active 

5 15 5 15 
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Statement 


Purpose: 


Writes a byte into a memory location. 


Versions: 


Cassette Disk Advanced Compiler 


Format: 


POKE n,m 


Remarks: 





n must be in the range to 65535. It indicates 

the offset into the current segment where that 
data is to be written. The current segment is 
defined by the DEF SEG statement. See 
"DEF SEG Statement." 

m m is the data to be written to the specified 
location. It must be in the range to 255. 

The complementary function to POKE is PEEK. 
POKE and PEEK are useful for efficient data 
storage and loading assembly language subroutines. 
See also "Peek Function." 

Warning: 

BASIC does not check the offset specified. So 
don't go POKEing around in BASIC'S stack, 
BASIC'S variable area, or your BASIC program. 

Example: See the examples in Appendix B, "Assembly 
Language Subroutines." 
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Purpose: Returns the current cursor column position. 
Versions: Cassette Disk Advanced Compiler 



Format: v = POS(») 

Remarks: n is a dummy argument. 

The current horizontal (column) position of the 
cursor is returned. The returned value is in the range 
1 to 40 or 1 to 80, depending on the current WIDTH 
setting. CSRLIN can be used to find the vertical 
(row) position of the cursor. See "CSRLIN 
Variable." 

See also "LPOS Function." 

Example: This example prints a carriage return (moves the 

cursor to the beginning of the next line) if the cursor 
is beyond position 60 on the screen. 

IF POS(0)>60 THEN PRINT CHR$(13) 
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Purpose: Displays data on the screen. 

Versions: Cassette Disk Advanced Compiler 



Format: 



Remarks: 



Remarks: 



PRINT [list of expressions] [;] 
? [list of expressions] [;] 



list of expressions 

is a list of numeric and/or string 
expressions, separated by commas, blanks, 
or semicolons. Any string constants in the 
list must be enclosed in quotation marks. 



If the list of expressions is omitted, a blank line is 
displayed. If the list of expressions is included, the 
values of the expressions are displayed on the screen. 

Print Positions 

The position of each printed item is determined by 
the punctuation used to separate the items in the list. 
BASIC divides the line into print zones of 14 spaces 
each. 

In the list of expressions: 

• Typing a comma between expressions causes the 
next value to be printed at the beginning of the 
next zone. 
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• Typing a semicolon causes the next value to be 
printed immediately after the last value. 

• Typing one or more spaces between expressions 
has the same effect as typing a semicolon. 

If a comma, semicolon, or SPC or TAB function 
ends the list of expressions, the next PRINT 
statement begins printing on the same line, spacing 
accordingly. If the list of expressions ends without a 
comma, semicolon, SPC or TAB function, a carriage 
return is printed at the end of the line; that is, 
BASIC moves the cursor to the beginning of the next 
line. 

If the length of the value to be printed exceeds the 
number of character positions remaining on the 
current line, the value is printed at the beginning of 
the next line. If the value to be printed is longer than 
the defined WIDTH, BASIC prints as much as it can 
on the current line and continues printing the rest of 
the value on the next physical line. 

Scrolling occurs as described under "Text Mode" in 
Chapter 3 of the BASIC Handbook. 

Printed numbers are always followed by a space. 
Positive numbers are preceded by a space. Negative 
numbers are preceded by a minus sign. When 
single-precision numbers can be represented with 7 
or fewer digits in fixed-point format as accurately as 
in floating point-format, they are returned in 
fixed-point or integer format. For example, 10a (-7) 
is printed as .0000001 and 10 a (-8) is output as 
1E-8. 

BASIC automatically inserts a carriage return/line 
feed after printing width characters, where width is 
40 or 80, as defined by the WIDTH statement. This 
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causes two lines to be skipped when you print 
exactly 40 (or 80) characters, unless the PRINT 
statement ends in a semicolon (;). 

LPRINT is used to print information on the printer. 
See "LPRINT and LPRINT USING Statements." 
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Example: In this example, the commas in the PRINT statement 
cause each value to be printed at the beginning of the 
next print zone. 



20 PRINT X+5, X-5, X*(-5) 
RUN 
10 -25 

Here, the semicolon at the end of line 20 causes 
both PRINT statements to be printed on the same 
line. 

10 INPUT X 

20 PRINT X;"SQUARED IS" ;X a2; "AND" ; 

30 PRINT X;"CUBED IS";Xa3 

RUN 

?9 

9 SQUARED IS 81 AND 9 CUBED IS 729 
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Purpose: Prints strings or numbers using a specified format. 
Versions: Cassette Disk Advanced Compiler 



Format: PRINT USING v$; list of expressions [;] 

Remarks: 

v$ is a string constant or variable that 

consists of special formatting 
characters. These formatting characters 
determine the field and the format of 
the printed strings or numbers. 

list of expressions 

consists of the string or numeric 
expressions that are to be printed, 
separated by semicolons or commas. 

String Fields 

When PRINT USING is used to print 
strings, one of three formatting 
characters can be used to format the 
string field: 

/ Specifies that only the first character in 

the given string is to be printed. 

\n spaces\ Specifies that 2 + n characters from the 
string are to be printed. If the 
backslashes are typed with no spaces, 
two characters are printed; with one 
space, three characters are printed, and 
so on. If the string is longer than the 
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PRINT USING 

Statement 



field, the extra characters are ignored. 
If the field is longer than the string, the 
string is left-justified in the field and 
padded with spaces on the right. 

Example: This example shows how to use / and 
\ \ to print string fields. 

10 A$="L00K":B$="0UT" 

20 PRINT USING "!";A$;B$ 

30 PRINT USING "\ \";A$;B$ 

RUN 

LO 

LOOKOUT 

& Specifies a variable-length string field. 

When the field is specified with "&", the 
string is output exactly as input. 
Example: 



10 A$="L00K": [ 
20 PRINT USING 
30 PRINT USING 
RUN 
LOUT 

Numeric Fields 



'OUT" 
';A$; 



When PRINT USING is used to print 
numbers, the following special 
characters can be used to format the 
numeric field: 

A number sign is used to represent each 
digit position. Digit positions are always 
filled. If the number to be printed has 
fewer digits than positions specified, the 
number is right- justified (preceded by 
spaces) in the field. 
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Statement 

A decimal point can be inserted at any 
position in the field. If the format string 
specifies that a digit is to precede the 
decimal point, the digit is always printed 
(as if necessary). Numbers are 
rounded as necessary. 

PRINT USING "##.##";. 78 
0.78 

Example: In this example, three spaces are inserted at the end 
of the format string to separate the printed values on 
the line. 

PRINT USING "##.## ";10. 2, 5. 3, 66. 789,. 234 
10.20 5.30 66.79 0.23 



+ A plus sign at the beginning or end of 

the format string causes the sign of the 
number (plus or minus) to be printed 
before or after the number. 

PRINT USING "+##.## ";-68.95,2.4,55.6,-.9 
-68.95 +2.40 +55.60 -0.90 



A minus sign at the end of the format 
field causes negative numbers to be 
printed with a trailing minus sign. 

PRINT USING "##.##- ";-68.95 s 22.449,-7.01 
68.95- 22.45 7.01- 



A double asterisk at the beginning of 
the format string causes leading spaces 
in the numeric field to be filled with 
asterisks. The ** also specifies positions 
for two more digits. 
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PRINT USING 

Statement 



PRINT USING "**#.# ";12. 39, -0.9, 765.1 
*12.4 *-0.9 765.1 



$$ A double dollar sign causes a dollar 

sign to be printed to the immediate left 
of the formatted number. The $$ 
specifies two more digit positions, one 
of which is the dollar sign. The 
exponential format cannot be used with 
$$. 

PRINT USING "$$###.## ";456. 78, 0.9, -765.1 
$456.78 $0.90 -$765.10 



The **$ at the beginning of a format 
string combines the effects of the above 
two symbols. Leading spaces are filled 
with asterisks, and a dollar sign is 
printed before the number. **$ 
specifies three more digit positions, one 
of which is the dollar sign. 

PRINT USING "**$##. ##";2. 34 
***$2.34 

A comma left of the decimal point in a 
formatting string prints a comma left of 
every third digit left of the decimal 
point. A comma at the end of the 
format string is printed as part of the 
string. A comma specifies another digit 
position. The comma has no effect if 
used with the exponential ( a a a a ) 
format. 
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Statement 



PRINT USING "####, .##" ;1234.5 
1,234.50 

PRINT USING "####. ##,";1234. 5 
1234.50, 

a a a a Four carets can be placed after the 

digit position characters to specify 
exponential format. The four carets 
allow space for E ± nn or D ± nn to be 
printed. Any decimal point position can 
be specified. The significant digits are 
left-justified, and the exponent is 
adjusted. Unless a leading + or trailing 
+ or - is specified, one digit position is 
used to the left of the decimal point to 
print a space or a minus sign. 

PRINT USING "##.##aaaa";234.56 
2.35E02 

nnTllT l\t-T\lf> II jijjj) , . » , II. OOOOO 

l-Kihl UJihu . fr## a a /\ /\ - „-ooooo 

.889E05- 

PRINT USING "+.##aaaa";123 
+.12E03 

An underscore in the format string 

causes the next character to be output 
as a literal character. 

PRINT USING "_!##. ##_!";12. 34 
112.34! 

The literal character itself can be an 

underscore by placing " " in the 

format string. 
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If the number to be printed is larger than the 
specified numeric field, a percent sign (%) is printed 
in front of the number. If rounding causes the 
number to exceed the field, the percent sign is 
printed in front of the rounded number. 

PRINT USING "##.##" ;111 .22 
%111 .22 

PRINT USING ".##";. 999 

%\.m 

If the number of digits specified exceeds 24, an 
Illegal function call error occurs. 

Example: This example shows how you can include string 
constants in the format string. 

PRINT USING "THIS IS EXAMPLE _##"; 1 
THIS IS EXAMPLE #1 
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PRINT # and PRINT # USING 

Statements 



Purpose: Writes data sequentially to a file. 

Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



PRINT ttfilenum, [USING x$;] list of exps [;] 



filenum is the number used when the file was 

opened for output. 

x$ is a string expression comprised of 

formatting characters as described in 
the previous entry, "PRINT USING 
Statement." 

list of exps is a list of the numeric and/or string 
expressions that will be written to the 
file. 

PRINT # does not compress data in the file. An 
image of the data is written to the file just as it would 
be displayed on the screen with a PRINT statement. 
For this reason, care should be taken to delimit the 
data in the file, so that it is input correctly from the 
file. 

In the list of expressions, numeric expressions should 
be delimited by semicolons. For example, 

PRINT #1,A;B;C;X;Y;Z 

(If commas are used as delimiters, the extra blanks 
inserted between print fields are also written to the 
file.) 
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PRINT # and PRINT # USING 
Statements 

String expressions must be separated by semicolons 
in the list. To format the string expressions correctly 
in the file, use explicit delimiters in the list of 
expressions. 

For example, let A$="CAMERA" and 
B$ = "93604-1". The statement 

PRINT #1,A$;B$ 

writes CAMERA93604-1 to the file. Because there 
are no delimiters, this could not be input as two 
separate strings. To correct the problem, insert 
explicit delimiters into the PRINT # statement as 
follows: 



\";i 



PRINT #1,A$; 

The image written to the file is 

CAMERA, 93604-1 

which can be read back into two string variables. 

If the strings themselves contain commas, 
semicolons, significant leading blanks, carriage 
returns, or line feeds, write them to the file 
surrounded by explicit quotation marks using 
CHR$(34). 

For example, let A$="CAMERA, AUTOMATIC" 
and B$=" 93604-1". The statement: 

PRINT #1,A$;B$ 

writes the following image to the file: 

CAMERA, AUTOMATIC 93604-1 

and the statement: 
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Statements 

INPUT #1,A$,B$ 

inputs the string "CAMERA" to A$ and 
"AUTOMATIC 93604-1" to B$. 

To separate these strings properly in the file, write 
double quotes to the file image using CHR$(34). 
The statement: 

PRINT #1,CHR$(34);A$;CHR$(34);CHR$(34);B$;CHR$(34) 

writes the following image to the file: 

"CAMERA, AUTOMATIC" "93604-1" 

and the statement: 

INPUT #1,A$,B$ 

inputs "CAMERA, AUTOMATIC" to A$ and 
"93604-1" to B$. 

The PRINT # statement can also be used with the 
USING option to control the format of the file. For 
example: 

PRINT #1 ,'uS I NG "$$###'. if it , ,u 3 i\;L 
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PRINT # and PRINT # USING 
Statements 

Example: Since data written to the file contains a dollar sign, 
use string variables to read them back, as in this 
example. 

10 A=123 

20 B=6789 

30 C=22.33 

40 OPEN "DATA" FOR OUTPUT AS #1 

50 PRINT #1, USING "$$###.##," ;A;B;C 

60 CLOSE 

70 OPEN "DATA" FOR INPUT AS #1 

80 INPUT #1,A$,B$,C$ 

90 CLOSE 

100 PRINT A$,B$,C$ 
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PSET and PRESET 

Statements 



Purpose: Draws a point at the specified position on the screen. 

Advanced Compiler 



Versions: 


Cassette Disk 




*** *** 




Graphics mode only. 


Format: 


PSET (x,y) [, color] 




PRESET (x,y) [,color] 


Remarks: 





(x,y) are the coordinates of the point to be set. 

They can be in absolute or relative form, 
as explained in "Specifying Coordinates" 
under "Graphics Modes" in Chapter 3 of 
the BASIC Handbook. 

color is an integer expression that chooses an 

attribute from the attribute range for the 
current screen mode. In medium 
resolution, the color is the current one for 
that attribute as defined by the COLOR 
statement. Four attributes (0-3) are 
available in medium resolution; in high 
resolution, two attributes (0-1) are 
available. Zero (0) is always the attribute 
for the background. The default 
foreground attribute is always the 
maximum attribute for that screen mode: 
3 in medium resolution; 1 in high 
resolution. 

PRESET is almost identical to PSET. The only 
difference is that if no color parameter is given to 
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PSET and PRESET 

Statements 

PRESET, the background attribute (0) is selected. 
If color is included, PRESET is identical to PSET. 
Line 70 in the example below could just as easily be: 

70 PSET(I , I ) ,0 

Out-of-range coordinates are clipped. 

Example: Lines 20-40 of this example draw a diagonal line 
from the point (0,0) to the point (100,100). Then 
lines 60-80 erase the line by setting each point to a 
color of 0. 

10 CLS:SCREEN 1 : KEY OFF 

20 FOR 1=0 TO 100 

30 PSET (1,1) 

40 NEXT 

50 'erase line 

60 FOR 1=100 TO STEP -1 

70 PRESETCI ,1) 

80 NEXT 
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PUT 

Statement (Files) 



Purpose: Writes a record from a random buffer to a random 
file. 

Versions: Cassette Disk Advanced Compiler 



Format: PUT [#]filenwn [,number] 
Remarks: 

filenum is the number under which the file was 
opened. 

number is the record number for the record to be 
written, in the range 1 to 16 megabytes. 

If number is omitted, the record has the next 
available record number (after the last PUT). 

PRINT #, PRINT # USING, WRITE #, LSET, and 
RSET can be used to put characters in the random 
file buffer before a PUT statement. In the case of 
WRITE #, BASIC pads the buffer with spaces up to 
the carriage return. 

Any attempt to read or write past the end of the 
buffer causes a Field overflow error. See also 
Appendix A, "BASIC Disk Input and Output," in 
the BASIC Handbook. 

Because BASIC and DOS block as many records as 
possible in 512-byte sectors, the PUT statement does 
not necessarily perform a physical write to the disk 
for each record. 
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Statement (Files) 



PUT can be used for a communications file. In that 
case number is the number of bytes to write to the 
communications file. This number must be less than 
or equal to the value set by the LEN option on the 
OPEN "COM... statement. 

Example: See Appendix A, "BASIC Disk Input and Output," 
in the BASIC Handbook. 
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PUT 

Statement (Graphics) 



Purpose: Plots images on a specified area of the screen. 
Versions: Cassette Disk 

Graphics mode only. 

PUT (x,y), array [,action] 



Advanced 



Compiler 



Format: 
Remarks: 



(x,y) are the coordinates of the top left corner 

of the image to be transferred. 

array is the name of a numeric array containing 
the information to be transferred. For 
more information on this array, see also 
"GET Statement (Graphics)." 

action is one of: 

PSET 

PRESET 

XOR 

OR 

AND 

XOR is the default. 

PUT is the opposite of GET in the sense that it takes 
data out of the array and puts it on the screen. 
However, it also provides the option of interacting 
with the data already on the screen. 

PSET simply stores the data from the array onto the 
screen, so this is the true opposite of GET. 
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PRESET is the same as PSET except that a 
complementary image is produced. For example, in 
medium resolution, which has a maximum attribute 
of 3, an attribute of in the array causes the 
corresponding point to be plotted with an attribute 
of 3, and vice versa; an attribute of 1 in the array 
causes the corresponding point to be plotted with an 
attribute of 2, and vice versa. 

AND, OR, and XOR specify the logical operations 
on the bits of each image. AND is used when an 
image already exists in the area to which the image is 
transferred. 

OR is used to superimpose the transferred image 
onto the existing image. 

XOR is a special mode that can be used for 
animation. Its unique property is that when an image 
is PUT against a complex background twice, the 
background is restored unchanged. This allows you 
to move an object around without obliterating the 
background. 

In medium resolution mode, AND, XOR, and OR 
have the following effects on color: 
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AND 



OR 



PUT 

Statement (Graphics) 



screen 


array value 
1 2 


3 











1 


1 


1 


2 


2 


2 


3 


1 2 


3 





array value 




screen 


1 2 


3 





1 2 


3 


1 


1 1 3 


3 


2 


2 3 2 


3 


3 


3 3 3 


3 
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XOR 



screen 


array value 
1 2 


3 





1 2 


3 


1 


1 3 


2 


2 


2 3 


1 


3 


3 2 1 






Animation of an object can be performed as follows: 

1. PUT the object on the screen (with XOR). 

2. Recalculate the new position of the object. 

3. PUT the object on the screen (with XOR) a 
second time at the old location to remove the old 
image. 

4. Repeat step 1 , this time putting the object at the 
new location. 

Movement done this way leaves the background 
unchanged. Flicker can be reduced by minimizing 
the time between steps 4 and 1 , and making sure 
there is enough time delay between steps 1 and 3. If 
more than one object is being animated, each object 
should be processed individually, one step at a time. 

If it is not important to preserve the background, 
animation can be performed using the PSET action 
verb. But you should remember to have an image 
area that will contain the "before" and "after" 
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Statement (Graphics) 

images of the object. This way the extra area 
effectively erases the old image. This method can be 
somewhat faster than the method using XOR 
described above, since only one PUT is required to 
move an object (although you must PUT a larger 
image). 

If the image to be transferred is too large to fit on 
the screen, an Illegal function call error occurs. 

Example: This example shows how to move a circle across the 
screen with XOR. 

10 CLS:DEFINT A-Z:SCREEN 1 : KEY OFF 

20 DIM A(404) 

30 CIRCLE (160,100), 20,3 

40 PAINT (160,100), 2, 3 

50 GET (140,80)-(180,120),A:CLS 

60 X=30: Y=50 

70 FOR 1=1 TO 20 

80 PUT (X,Y),A,X0R 

90 PUT (X,Y),A,X0R 

100 X=X + 10 

110 NEXT 
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RANDOMIZE 
Statement 



Purpose: 
Versions: 

Format: 
Remarks: 



Reseeds the random number generator. 
Cassette Disk Advanced Compiler 

RANDOMIZE [n] 
RANDOMIZE TIMER 



n is an integer, single-, or double-precision 

expression that is used as the random number 
seed. In Cassette BASIC, n must be an 
integer expression. 

If n is omitted, BASIC suspends program execution 
and asks for a value by displaying: 

Random Number Seed (-32768 to 32767)? 

before executing RANDOMIZE. 

If the random number generator is not reseeded, the 
RND function returns the same sequence of random 
numbers each time the program is run. To change 
the sequence of random numbers every time the 
program is run, place a RANDOMIZE statement at 
the beginning of the program and change the seed 
with each run. 

In Disk BASIC and Advanced BASIC, the internal 
clock can be a useful way to get a random number 
seed. You can use VAL to change the last two digits 
of TIME$ to a number, and then use that number for 
n. 
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RANDOMIZE 

Statement 

You can get a new random number seed without 
being prompted. To do this, use the TIMER 
function in the expression. (For BASIC 2.0 and later 
releases.) 



10 RANDOMIZE 
20 FOR 1=1 TO 4 
30 PRINT RND; 
40 NEXT I 

RUN 

Random Number Seed (-32768 to 32767)? 

Suppose you respond with 3. The program 
continues: 

Random Number Seed (-32768 to 32767)? 3 

.7655695 .3558607 .3742327 .1388798 
RUN 

Random Number Seed (-32768 to 32767)? 

Suppose this time you respond with 4. The program 
continues: 

Random Number Seed (-32768 to 32767)? 4 

.1719568 .5273236 .6879686 .713297 
RUN 

Random Number Seed (-32768 to 32767)? 

If you try 3 again, you'll get the same sequence as 
the first run: 

Random Number Seed (-32768 to 32767)? 3 
.7655695 .3558607 .3742327 .1388798 
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Statement 



This example uses TIMER. Note that each time the 
program is run you see a different sequence of 
numbers. 

10 RANDOMIZE TIMER 
20 FOR 1=1 TO 4 
30 PRINT RND; 
40 NEXT 
RUN 

.9590051 .1036786 .1464037 .7754918 
RUN 

.8261163 .17422 .9191545 .5041142 
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READ 

Statement 



Purpose: Reads values from a DATA statement and assigns 
them to variables. See "DATA Statement." 

Versions: Cassette Disk Advanced Compiler 



Format: READ variable ^variable]... 

Remarks: 

variable is a numeric or string variable or array 
element that is to receive the value read 
from the DATA table. 

A READ statement must always be used with a 
DATA statement. READ statements assign DATA 
statement values to the variables in the READ 
statement on a one-to-one basis. 

READ statement variables can be numeric or string, 
and the values that are read must agree with the 
variable types specified. If they do not agree, a 
Syntax error results. 

A single READ statement can access one or more 
DATA statements (they are accessed in order), or 
several READ statements can access the same 
DATA statement. If the number of variables in the 
list of variables exceeds the number of elements in 
the DATA statement(s), an Out of data error occurs. 
If the number of variables specified is fewer than the 
number of elements in the DATA statement(s), 
subsequent READ statements begin reading data at 
the first unread element. If there are no subsequent 
READ statements, the extra data is ignored. 
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Statement 

To reread data from any line in the list of DATA 
statements, use the RESTORE statement. See 
"RESTORE Statement." 

Example: This program segment reads the values from the 

DATA statements into the array A. After execution, 
the value of A(l) is 3.08, and so on. 

10 FOR 1=1 TO 10 

20 READ A(I) 

30 NEXT I 

40 DATA 3.08,5.19,3.12,3.98,4.24 

50 DATA 5.08,5.55,4.00,3.16,3.37 

This program reads string and numeric data from 
the DATA statement in line 30. Note that you do 
not need quotation marks around COLORADO, 
because it does not have commas, semicolons, or 
significant leading or trailing blanks. However, you 
do need the quotation marks around "DENVER," 
because of the comma. 

10 PRINT "CITY", "STATE", " ZIP" 

20 READ C$,S$,Z 

30 DATA "DENVER,", COLORADO, 80211 

40 PRINT C$,S$,Z 

RUN 

CITY STATE ZIP 

DENVER, COLORADO 80211 
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REM 

Statement 



Purpose: Inserts explanatory remarks in a program. 
Versions: Cassette Disk Advanced Compiler 

Format: REM remark 

Remarks: remark can be any sequence of characters. 

REM statements are not executed, but are displayed 
when the program is listed exactly as they were 
entered. However, they do slow execution time 
somewhat and take up space in memory. 

REM statements can be branched into (from a 
GOTO or GOSUB statement), and execution 
continues with the first executable statement after 
the REM statement. 

Remarks can be added by preceding the remark with 
a single quotation mark instead of :REM. If you put 
a remark on a line with other BASIC statements, the 
remark must be the last statement on the line. 

You cannot use the single quote (') to add comments 
at the end of a DATA statement. If you do, BASIC 
thinks it is part of a string. You can, however, use 
:REM to add a remark. 
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Statement 

Example: This example shows the two ways to insert remarks 
in a program. 

10 'calculate average velocity 
20 SUM=0: REM initialize SUM 
30 FOR 1=1 TO 20 
40 SUM=SUM + V(I) 

Line 20 might also be written: 

20 SUM=0 ' initialize SUM 
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RENUM 

Command 



Purpose: Renumbers program lines. 



Versions: Cassette Disk 



Advanced Compiler 

*** 



Format: RENUM [newnum] [,[oldnum\ ^increment]] 
Remarks: 

newnum is the first line number to be used in the 
new sequence. The default is 10. 

oldnum is the line in the current program where 

renumbering is to begin. The default is 
the first line of the program. 

increment is the amount each line number will 
increase in the new sequence. The 
default is 1 0. 

To reflect the new line numbers, RENUM also 
changes all line number references following ELSE, 
GOSUB, GOTO, ON.. .GOTO, ON...GOSUB, 
RESTORE, RESUME, THEN and ERL test 
statements. If a nonexistent line number appears 
after one of these statements, the error message 
Undefined line number xxxxx in yyyyy is displayed. 
The incorrect line number reference (xxxxx) is not 
changed by RENUM, but line number yyyyy may be 
changed. 

Note: RENUM cannot be used to change the 
order of program lines or to create line numbers 
greater than 65529. An attempt to do so results 
in an Illegal function call error. 
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Command 

Example: This example renumbers the entire program. The 

first new line number is 1 0. Line numbers increment 
by 10. 

RENUM 

This example also renumbers the entire program. 
The first new line number is 300. Line numbers 
increment by 50. 

RENUM 300,, 50 

This example renumbers the lines from 900 up so 
they start with line number 1 000 and increment by 
20. 

RENUM 1000,900,20 
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RESET 

Command 

Purpose: Closes all disk files and clears the system buffer. 
Versions: Cassette Disk Advanced Compiler 

Format: RESET 

Remarks: If all open files are on disk, RESET is the same as 
CLOSE with no file numbers after it. 
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RESTORE 

Statement 



Purpose: Allows DATA statements to be reread from a 
specified line. 

Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



Example: 



RESTORE [line] 



line is the line number of a DATA statement in 
the program. 

After a RESTORE statement is executed, the next 
READ statement accesses the first item in the first 
DATA statement in the program. If line is specified, 
the next READ statement accesses the first item in 
the specified DATA statement. 

In this example, the RESTORE statement in line 20 
resets the DATA pointer to the beginning so that the 
values that are read in line 30 are 57, 68, and 79. 

10 READ A,B,C 
20 RESTORE 
30 READ D,E,F 
40 DATA 57, 68, 79 
50 PRINT A;B;C;D;E;F 
RUN 
57 68 79 57 68 79 
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RESUME 
Statement 



Purpose: Continues program execution after an error recovery 
procedure is performed. 

Versions: Cassette Disk Advanced Compiler 

Format: RESUME [0] 

RESUME NEXT 

RESUME line 

Remarks: Any of the formats shown above can be used, 
depending on where execution is to resume: 

RESUME or RESUME 

Execution resumes at the statement 
that caused the error. 

Note: If you try to renumber a 
program containing a 
RESUME statement, you will 
get an Undefined line number 
error. The statement will still say 
RESUME 0, which is okay. 

RESUME NEXT 

Execution resumes at the statement 
immediately following the one that 
caused the error. 

RESUME line Execution resumes at the specified 
line number. 
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RESUME 

Statement 

A RESUME statement that is not in an error trap 
routine causes a RESUME without error message to 
occur. 

Example: In this example, line 1000 is the beginning of the 
error trapping routine. The RESUME statement 
causes the program to return to line 80 when error 
230 occurs in line 90. 

10 ON ERROR GOTO 1 



1000 IF (ERR=230)AND(ERL=90) THEN PRINT 
"TRY AGAIN": RESUME 80 
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RETURN 

Statement 



Purpose: Stops a subroutine and returns to the main program. 
See "GOSUB and RETURN Statements." 



Versions: 


Cassette Disk 




*** *** 


Format: 


RETURN [line] 


Remarks: 





Advanced Compiler 



line is the number of the program line you wish to 
return to. You can use it only in Advanced 
BASIC and BASIC Compiler. 

Although you can use RETURN line to return from 
any subroutine, this enhancement was added to allow 
nonlocal returns from the event trapping routines. 
From one of these routines you will often want to go 
back to the BASIC program at a fixed line number 
while still eliminating the GOSUB entry the trap 
created. The nonlocal RETURN must be used with 
care, however, since any other GOSUB, WHILE, or 
FOR statements active at the time of the trap remain 
active. 
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RIGHTS 

Function 

Purpose: Returns the rightmost n characters of string x$. 
Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



v$ = RIGHTS (x&w) 



x$ is any string expression. 

n is an integer expression that specifies the 

number of characters to be in the result. 

If n is greater than or equal to LEN(x#), then x$ is 
returned. If n is zero, the null string (length zero) is 
returned. 

See also "MID$" and "LEFT$" functions. 

Example: In this example, the rightmost seven characters of the 
string A$ are returned. 

10 A$="B0CA RATON, FLORIDA" 
20 PRINT RIGHT$(A$,7) 
RUN 
FLORIDA 
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RMDIR 

Command 



Purpose: Removes a directory from the specified disk. (For 
BASIC 2.0 and later releases.) 

Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



Example: 



RMDIR path 



path is a string expression, not exceeding 63 

characters, that identifies the subdirectory 
to be removed from the existing directory. 
See also "Naming Files" and 
"Tree-Structured Directories" in Chapter 
3 of the BASIC Handbook for more 
information. 

The directory must be empty of all files and 
subdirectories before it can be removed, with the 
exception of the "." and ".." entries, or a Path/file 
access error occurs. 



ROOT 



SALES 



ACCTING 



MIKE 



SHANNON CHELLE 



ALICE 
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Command 



The examples that follow refer to the tree structure 
shown on the preceding page. 

If you are in the root directory and you want to 
remove the directory called ALICE, use: 

RMDIR "SALES\MIKE\ALICE" 

If you want to make ACCTING the current 
directory and remove the directory called CHELLE, 
use: 

CHDIR "ACCTING" 
RMDIR "CHELLE" 

Another way to remove the directory CHELLE is 
to make the root the current directory and then 
remove CHELLE. 

CHDIR "\" 

RMDIR "ACCTING\CHELLE" 

The directory preceding the current directory 
cannot be removed. Using the same tree structure, 
suppose that MIKE is the current directory. If you 
try to remove the SALES directory, you will get a 
Path/file access error. 

If you try to use the KILL command to remove a 
directory, you will get a Path/file access error. 
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RND 

Function 



Purpose: Returns a random number between and 1. 
Versions: Cassette Disk Advanced Compiler 



Format: v = RND[(x)] 
Remarks: 

x is a numeric expression that affects the 

returned value as described below. 

The same sequence of random numbers is generated 
each time the program is run unless the random 
number generator is reseeded. Reseeding is most 
easily done by using the RANDOMIZE statement. 
See "RANDOMIZE Statement." 

You can also reseed the generator when you call the 
RND function by using x where x is negative. This 
always generates the particular sequence for the 
given x. This sequence is not affected by 
RANDOMIZE, so if you want it to generate a 
different sequence each time the program is run, you 
must use a different value for x each time. 

If x is positive or not included, RND(x) generates the 
next random number in the sequence. 

RND(0) repeats the last number generated. 

To get random numbers in the range (zero) 
through n, use the formula: 

INKRND * (n+1)) 
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Function 

Example: In this example, the first horizontal line of results 
shows three random numbers, generated using a 
positive x. 

In line 40, a negative number is used to reseed the 
random number generator. The random numbers 
produced after this reseeding are in the second row 
of results. 

In line 80, the random number generator is reseeded 
using the RANDOMIZE statement; in line 90 it is 
reseeded again by calling RND with the same 
negative value as in line 40. This cancels the effect 
of the RANDOMIZE statement, as you can see; the 
third line of results is identical to the second line. 

In line 130, RND is called with an argument of 0, so 
the last number printed is the same as the preceding 
number. 

10 FOR 1=1 TO 3 

20 PRINT RND(I); ' x>0 

30 NEXT I 

40 PRINT: X=RND(-6) ' x<0 

50 FOR 1=1 TO 3 

60 PRINT RND(I); ' x>0 

70 NEXT I 

80 RANDOMIZE 853 ' randomize 

90 PRINT: X=RND(-6) ' x<0 

100 FOR 1=1 TO 3 

110 PRINT RND; ' same as x>0 

120 NEXT I 

130 PRINT: PRINT RND(0) 

RUN 

.6291626 .1948297 .6305799 

.6818615 .4193624 .6215937 

.6818615 .4193624 .6215937 

.6215937 
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Function 

Reseeding with the RND (negative number) 
function reseeds through permutation of the last 
floating point temporary. Since no floating point 
calculations are done in this example, the new seed is 
always the same. 

10 DEFINT A-Z 

20 FOR J=l TO 5 

30 X=RND(-J) 

40 FOR 1=1 TO 5:PRINT RND;NEXT:PRINT 

50 NEXT J 

If line 20 is changed to: 

20 FOR J=l TO 2 STEP .1 

a new seed is generated each time. 
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RUN 

Command 

Purpose: Begins execution of a program. 



Versions: Cassette Disk 

Format: RUN [line] 

RUN filespec[,R] 
Remarks: 



Advanced 
*** 



Compiler 



line is the line number of the program in 

memory where you want execution to 
begin. 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. Filespec 
must conform to the rules outlined 
under "Naming Files" in Chapter 3 of 
the BASIC Handbook; otherwise, an 
error occurs. 

RUN or RUN line begins execution of the program 
currently in memory. If line is specified, execution 
begins with the specified line number. Otherwise, 
execution begins at the lowest line number. 

RUN filespec loads a file from disk or cassette into 
memory and runs it. It closes all open files and 
deletes the current contents of memory before 
loading the designated program. However, with the 
R option, all data files remain open. See also 
Appendix A, "BASIC Disk Input and Output" in the 
BASIC Handbook. 
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Command 

Executing a RUN command turns off any sound that 
is running and resets to Music Foreground. Also, 
PEN and STRIG are reset to OFF. 

Example: The first example shows the first form of RUN in 
two very short programs. The first program is run 
from the beginning. The RUN line option in the 
second example runs the program from line 20. In 
this case, line 10 is not executed, so PI does not 
receive its proper value. A is printed because all 
numeric variables have an initial value of zero. 

10 PRINT 1/7 
RUN 
.1428571 

10 PI=3. 141593 
20 PRINT PI 
RUN 20 



This example loads the program "NEWFIL" and 
runs it, keeping files open. 

RUN "NEWFIL", R 
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Command 

Purpose: Saves a BASIC program file on disk or cassette. 
Versions: Cassette Disk Advanced Compiler 

Format: SAVE filespec [, A] 

SAVE filespec [,P] 

Remarks: 

filespec is a string expression for the file 

specification. In BASIC 2.0 and later 
releases, it can contain a path. Filespec 
must conform to the rules outlined 
under "Naming Files" in Chapter 3 of 
the BASIC Handbook; otherwise, an 
error occurs. 

The BASIC program is written to the specified 
device. When the program is being saved to CAS1:, 
the cassette motor is turned on and the file is 
immediately written to the tape. 

For disk files, if the filename is eight characters or 
less and no extension is supplied, the extension .BAS 
is added to the name. If a file with the same 
filename already exists on the diskette, it will be 
written over. 

In Cassette BASIC, if the device name is omitted, 
CAS1: is assumed. CAS1: is the only device allowed 
for SAVE in Cassette BASIC. 

For Disk BASIC and Advanced BASIC, the device 
defaults to the DOS default drive. 
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The A option saves the program in ASCII format. 
Otherwise, BASIC saves the file in a compressed 
binary (tokenized) format. ASCII files take up more 
space, but some types of access require that files be 
in ASCII format. For example, a file intended to be 
merged must be saved in ASCII format. Programs 
saved in ASCII can be read as data files. 

The P (protection) option saves the program in an 
encoded binary format. When a protected program is 
later run (or loaded), any attempt to LIST or EDIT it 
fails with an Illegal function call error. No way is 
provided to "unprotect" such a program. 

Note: The disk directory entry for a BASIC 
program file gives no indication that the file is 
either protected or stored in ASCII format. The 
.BAS extension is used in any case. 

See also Appendix A, "BASIC Disk Input and 
Output," in the BASIC Handbook. 

Example: This example saves the program in memory as 
INVENT with the default extension .BAS. 

SAVE "INVENT" 

This example saves PROG. BAS on drive B in 
ASCII, so it can be merged later. 

SAVE "B:PR0G",A 

This example saves SECRET. BOZ on drive A, 
protected, so it cannot be altered. 

SAVE "A:SECRET.BOZ",P 
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SCREEN 

Function 



Purpose: 



Versions: 



Returns the ASCII code (0-255) for the character on 
the active screen at the specified row (line) and 
column. 



Cassette 

*** 



Disk 

*** 



Advanced 

**# 



Compiler 



Format: 
Remarks: 



v = SCREEN(row,col[,z]) 

row is a numeric expression in the range 1 to 25. 

col is a numeric expression in the range 1 to 40 or 
1 to 80, depending on the WIDTH setting. 

z is a numeric expression that evaluates to a 

true or false value, z is valid only in text 
mode. 

For a list of ASCII codes, See Appendix D, "ASCII 
Character Codes." 

In text mode, if z is included and is true (nonzero), 
the color attribute for the character is returned 
instead of the code for the character. The color 
attribute is a number in the range to 255. This 
number, v, is deciphered as follows: 

(v MOD 16) is the foreground attribute. 

(((v - foreground) /16) MOD 128) is the 
background attribute, where foreground is 
calculated as above. 
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Function 

(v>127) is true (-1) if the character is blinking; 
false (0) if it is not. 

For a list of colors and their associated attributes, see 
"COLOR Statement." 

In graphics mode, if the specified location contains 
graphic information (points or lines, not just a 
character), then the SCREEN function returns 0. 

Any values entered outside the ranges indicated 
result in an Illegal function call error. 

The SCREEN statement is explained in the next 
entry. 

Example: In this example, if the character at 10,10 is A, then 
Xis65. 

100 X = SCREEN (10,10) 

This example returns the color attribute of the 
character in the upper left-hand corner of the screen. 

110 X - SCREEN (1,1,1) 



311 



SCREEN 

Statement 



Purpose: Sets the screen attributes to be used by subsequent 
statements. 

Versions: Cassette Disk Advanced Compiler 

Meaningful with the Color/Graphics Monitor 
Adapter only. 

Format: SCREEN [mode] [,[burst] [,[apage] [,vpage]]] 

Remarks: 

mode is a numeric expression resulting in an 

integer value of 0, 1 , or 2. Valid modes 
are: 

Text mode at current width (40 or 
80). 

1 Medium resolution graphics mode 
(320x200). Use only with 
Color/Graphics Monitor Adapter. 

2 High resolution graphics mode 
(640x200). Use only with 
Color/Graphics Monitor Adapter. 

burst is a numeric expression resulting in a true 

or false value. It enables or disables color. 
On an RGB monitor, color burst is always 
on. On a composite monitor, color burst 
can be on or off. In text mode (mode=0), 
a false (zero) value disables color (only 
the monochrome images are displayed) ; a 
true (nonzero) value enables color (color 
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Statement 

images are displayed). In medium 
resolution graphics mode (mode=l), a true 
(nonzero) value disables color, and a false 
(zero) value enables color. Since high 
resolution graphics are only two colors 
(black and white), this parameter has no 
effect in high resolution. 

apage (active page) is an integer expression in 
the range to 7 for width 40 ;0 to 3 for 
width 80. It selects the page to be written 
to by output statements to the screen, and 
is valid only in text mode (mode=fi). 

vpage (visual page) selects the page to be 

displayed on the screen, in the same way 
as apage above. The visual page can be 
different from the active page, vpage is 
valid only in text mode (mode=0). If 
omitted, vpage defaults to apage. 

If all parameters are valid, the new screen mode is 
stored; the screen is erased; the foreground color is 
set to white; and the background and border colors 
are set to black. 

If the new screen mode is the same as the previous 
mode, nothing is changed. 

If the mode is text and only apage and vpage are 
specified, display pages are changed for viewing. 
Initially, both active and visual pages default to 
(zero). By manipulating active and visual pages, you 
can display one page while building another. Then 
you can switch visual pages instantaneously. 

If you mix text and graphics in the 40= or 80= 
column graphics mode and are not using a U.S. 
keyboard, refer to "GRAFT ABL Command" in the 
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Disk Operating System Reference for information 
regarding additional character support with the 
Color/Graphics monitor. 

Note: Only one cursor is shared among all the 
pages. If you are going to switch active pages 
back and forth, you should save the cursor 
position on the current active page (using 
POS(0) and CSRLIN), before changing, to 
another active page. Then when you return to 
the original page, you can restore the cursor 
position using the LOCATE statement. 

Any parameter can be omitted. Omitted parameters, 
except vpage, assume the old value. 

Any values entered outside the ranges indicated 
result in an Illegal function call error. Previous values 
are retained. 

Example: This example selects text mode with color burst 
enabled, and sets active and visual page to 0. 

10 SCREEN 0,1,0,0 

In this example, mode and color burst remain 
unchanged. Active page is set to 1 and display page 
to 2. 

10 SCREEN ,,1,2 
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This example switches to high-resolution graphics 
mode. 

10 SCREEN 2,, 0,0 

This example switches to medium-resolution color 
graphics, color burst enabled. 

10 SCREEN 1,0 

This example sets medium-resolution graphics with 
color burst disabled. 

50 SCREEN ,1 
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Function 

Purpose: Returns the sign of x. 

Versions: Cassette Disk Advanced Compiler 

Format: v = SGN(x) 

Remarks: x is any numeric expression. 

SGN(jc) is the mathematical signum function: 

• If x is positive, SGN(x) returns 1. 

• If x is zero, SGN(jt) returns 0. 

• If x is negative, SGN(jc) returns -1. 

Example: This example branches to 100 if X is negative; 200 
if X is zero; and 300 if X is positive. 

ON SGN(X)+2 GOTO 100,200,300 
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SHELL 

Statement 



Purpose: Loads and executes another program file (such as 
files with the .COM, .BAT, and .EXE extensions). 
Any program executed under BASIC is referred to as 
a child process. When the child process has finished 
executing, control returns to the parent BASIC 
program at the statement following the SHELL 
statement. 

(Not valid for BASIC releases earlier than 3.0.) 
Versions: Cassette Disk Advanced Compiler 

Format: SHELL [command string] 
Remarks: 



command string 



is a string expression containing 
the name of a program to run, 
and, optionally, any parameters 
you are passing to the child 
process. 



Child processes are executed by SHELL loading and 
running a copy of COMMAND.COM with the /C 
switch. By using COMMAND in this way any 
parameters you can have are correctly passed into 
the default File Control Blocks. Standard input and 
output can be redirected, and built-in commands 
such as DIR, PATH, and SORT can be executed. If 
you enter SHELL with no command string, a copy of 
COMMAND.COM is loaded, the DOS prompt 
appears, and you can enter any commands that are 
valid under DOS (DIR, COPY, SORT, ETC.). You 
can return to BASIC by typing the word EXIT. You 
can also invoke batch files from the SHELL 
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statement. To return to the parent BASIC program, 
your batch file must contain EXIT as the last 
statement of the batch file. 

When running child processes from a BASIC 
application using the SHELL statement, there are 
some procedures and rules that your application 
should follow. Going outside the boundaries of these 
guidelines could cause your application to fail or 
produce unpredictable results. 

To guarantee that you return to BASIC from your 
child process in the the screen mode that you expect, 
you can do one of two things: 

• Use BIOS Interrupt 10H, function call 15, to 
save the current video mode. When your child 
process returns to DOS, use function call to 
restore the video mode. 

• From your BASIC program, execute a SCREEN 
statement followed by a CLS statement 
immediately after the SHELL statement. 

Before BASIC executes a SHELL statement, it saves 
any interrupt vectors it uses; but this does not ensure 
that any interrupt vectors your routines use, and are 
not used by BASIC, are restored. So be sure to save 
any interrupt vectors your routine uses to preserve 
the proper interface to DOS. 

Certain devices must be left untouched to ensure 
that they are exactly as DOS and BASIC expect 
them to be. These devices are the 8259 interrupt 
controller, the 8253 counter timer, the 8237 DMA 
controller, the 8255 I/O latch, and the 8250 
asynchronous communications element. Further 
descriptions of these devices can be found in the 
IBM Personal Computer Technical Reference manual. 
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A child process that alters any file opened by the 
BASIC application can have unpredictable results. If 
you must update such files, be sure to close them 
from your BASIC application before executing a 
SHELL to your child process. Remember that files 
that were opened under redirection of standard input 
and output constitute OPEN files and that these files 
should not be modified in a SHELLed process. 

Before BASIC executes a SHELL statement, it frees 
any memory it is not using except when BASIC is 
invoked with the /M: switch. Because BASIC was 
invoked with the /M: switch, BASIC assumes that a 
assembly language routine will be loaded just beyond 
BASIC'S data segment. This prevents BASIC from 
compressing its workspace before executing a 
SHELL and, consequently, SHELL can fail with an 
Out of memory error when using the /M: switch. 

The preferred method for running applications that 
use the SHELL statement is to load the assembly 
language subroutines before you run BASIC. This 
involves placing code in your subroutines that, when 
invoked from DOS, allows them to terminate and 
stay resident (INT 27H). For more information 
refer to Appendix B, "Assembly Language 
Subroutines." 

Any routine that you execute from the SHELL 
statement should never terminate and stay resident. 
Doing so may not leave BASIC enough room to 
restore its workspace. All files are closed, the error 
message Can't continue after SHELL is printed, and 
BASIC exits to DOS. 

BASIC remains in memory while the child process is 
running. When the child process finishes, BASIC 
continues. 
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A program name in command string can have any 
extension you choose. If you do not supply an 
extension, DOS looks for a .COM extension, then a 
.EXE extension, and finally a .BAT extension. If the 
filename is not located during this search, 
COMMAND issues an error message. 

Any text separated from a program name supplied in 
command string by at least one blank is processed as 
program parameters. 

When BASIC is run, its environment is inherited 
from DOS. Any changes your application makes to 
BASIC'S environment are reflected in the 
environment for the child process. 

Note: For more information on environment, see 
"Detailed Descriptions of Advanced DOS 
Commands" in Disk Operating System (DOS 
manual). 

You cannot SHELL to BASIC. If you attempt to run 
BASIC as a child process, you will receive an error 
message. After this message is displayed, control 
returns to the BASIC parent. 

Example: This example creates a file, exits to the DOS SORT 
utility, and then returns to BASIC. 

10 OPEN "SORTIN.DAT" FOR OUTPUT AS #1 
20 'writes data to be sorted 



CLOSE 1 

110 SHELL "SORT <SORTIN.DAT >S0RT0UT.DAT" 
120 OPEN "S0RT0UT.DAT" FOR INPUT AS #1 
130 'processes the sorted data 
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The following example displays a disk directory 
from BASIC. 

SHELL 

A>DIR (type DIR command at DOS prompt) 

A>EXIT (type EXIT to return to BASIC) 

The same result can be achieved with: 

SHELL "DIR". 
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Function 



Purpose: Calculates the trigonometric sine function. 
Versions: Cassette Disk Advanced Compiler 



Format: v = SIN(x) 

Remarks: x is an angle in radians. 

To convert degrees to radians, multiply by PI/ 180, 
where PI=3. 141593. 

In BASIC 2.0 and later releases, you can have this 
calculation performed in double precision by 
specifying /D on the BASIC command line when 
BASIC is initially loaded. See "Options in the 
BASIC Command" in the BASIC Handbook. 

Example: This example calculates the sine of 90 degrees after 
first converting the degrees to radians. 



10 PI=3. 141593 
20 DEGREES = 90 
30 RADIANS=DEGREES * PI/1! 
40 PRINT SIN(RADIANS) 
RUN 
1 



PI/2 
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Purpose: Generates sound through the speaker. 
Versions: Cassette Disk Advanced Compiler 

Format: SOUND freq, duration 
Remarks: 

freq is the desired frequency in Hertz (cycles 

per second). It must be a numeric 
expression in the range 37 to 32767. 

duration is the desired duration in clock ticks. 
The clock ticks occur 18.2 times per 
second, duration must be a numeric 
expression. In Disk BASIC, duration is 
.027 to 65535. In Advanced BASIC, 
duration is .0015 to 65535. 

When the SOUND statement produces a sound, the 
program continues to execute until another SOUND 
statement is reached. If duration of the new SOUND 
statement is 0, the currently running SOUND 
statement is turned off. Otherwise, the program 
waits until the first sound completes before it 
executes the new SOUND statement. 

If you are using Advanced BASIC, you can cause the 
sounds to be buffered so execution does not stop 
when a new SOUND statement is encountered. See 
the explanation of the MB (Music Background) 
command under "PLAY Statement." 

If no SOUND statement is running, SOUND x,0 has 
no effect. 
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The tuning note, A, has a frequency of 440. The 
following table correlates notes with their 
frequencies. 



Note 


Frequency 


Note 


Frequency 


C 


130.810 


C 


523.250 


D 


146.830 


D 


587.330 


E 


164.810 


E 


659.260 


F 


174.610 


F 


698.460 


G 


196.000 


G 


783.990 


A 


220.000 


A 


880.000 


B 


246.940 


B 


987.770 


C* 


261.630 


C 


1046.500 


D 


293.660 


D 


1174.700 


E 


329.630 


E 


1318.500 


F 


349.230 


F 


1396.900 


G 


392.000 


G 


1568.000 


A 


440.000 


A 


1760.000 


B 


493.880 


B 


1975.500 



* middle C. Higher (or lower) notes can be 
approximated by doubling (or halving) the frequency 
of the corresponding note in the previous (next) 
octave. 

To create periods of silence, use SOUND 
321 61, duration. 

The duration for one beat can be calculated from 
beats per minute by dividing the beats per minute 
into 1092 (the number of clock ticks in a minute). 
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The next table shows typical tempos in terms of 
clock ticks: 





Tempo 


Beats/ 
Minute 


Ticks/ Beat 


very slow 


Larghissimo 








Largo 


40-60 


27.3-18.2 




Larghetto 


60-66 


18.2-16.55 




Grave 








Lento 








Adagio 


66-76 


16.55-14.37 


slow 


Adagietto 








Andante 


76-108 


14.37-10.11 


medium 


Andantino 








Moderato 


108-120 


10.11-9.1 


fast 


Allegretto 








Allegro 


120-168 


9.1-6.5 




Vivace 








Veloce 








Presto 


168-208 


6.5-5.25 


very fast 


Prestissimo 







Example: The following program creates a glissando (sliding up 
and down the scale). 



10 FOR 1=440 TO 1000 STEP 5 

20 SOUND I, 0.5 

30 NEXT 

40 FOR 1=1000 TO 440 STEP -5 

50 SOUND 1,7 0.5 

60 NEXT 
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Function 

Purpose: Returns a string consisting of n spaces. 
Versions: Cassette Disk Advanced Compiler 

Format: v$ = SPACES (n) 

Remarks: n must be in the range to 255. 

See also "SPC Function." 

Example: This example uses the SPACES function to print 
each number I on a line preceded by I spaces. An 
additional space is inserted because BASIC puts a 
space in front of positive numbers. 

10 FOR I = 1 TO 5 
20 X$ = SPACE$(I) 
30 PRINT X$;I 
40 NEXT I 
RUN 
1 
2 
3 
4 
5 
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Function 



Purpose: Skips n spaces in a PRINT statement. 



Versions: Cassette Disk 



Advanced Compiler 



Format: PRINT SPC(«) 

Remarks: n must be in the range to 255. 

If n is greater than the defined width of the device, 
the value used is n MOD width. SPC can be used 
only with PRINT, LPRINT, and PRINT # 
statements. 

If the SPC function is at the end of the list of data 
items, BASIC does not add a carriage return, as 
though the SPC function had an implied semicolon 
after it. 

See also "SPACES Function." 

Example: This example prints OVER and THERE separated 
by 15 spaces. 

PRINT "OVER" SPCC15) "THERE" 
OVER THERE 
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Function 



Purpose: Returns the square root of x. 

Versions: Cassette Disk Advanced Compiler 



Format: v = SQR(x) 

Remarks: x must be greater than or equal to zero. 

In BASIC 2.0 and later releases, you can have this 
calculation performed in double-precision by 
specifying /D on the BASIC command line when 
BASIC is initially loaded. See "Options in the 
BASIC Command" in the BASIC Handbook. 

Example: This example calculates the square roots of the 
numbers 10, 15, 20, and 25. 

10 FOR X = 10 TO 25 STEP 5 
20 PRINT X, SQR(X) 
30 NEXT 
RUN 

10 3.162278 

15 3.872984 

20 4.472136 

25 5 
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Function 

Purpose: Returns the x and y coordinates of two joysticks. 
Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



v = STICKS) 



n is a numeric expression in the range to 3 

that affects the result as follows: 

returns the x coordinate for joystick A. 

1 returns the y coordinate of joystick A. 

2 returns the x coordinate of joystick B. 

3 returns the y coordinate of joystick B. 

Note: STICK(0) retrieves all four values for the 
coordinates, and returns the value for STICK(0). 
STICK(l), STICK(2), and STICK(3) get the 
values previously retrieved by STICK(0). 

The range of values for x and y depends on your 
particular joysticks. 
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Example: This program prints 100 samples of the coordinates 
of joystick B. 

10 PRINT "Joystick B" 

20 PRINT "x coordinate" , "y coordinate" 

30 FOR J=l TO 100 

40 TEMP=STICK(0) 

50 X=STICK(2): Y=STICK(3) 

60 PRINT X,Y 

70 NEXT 



330 





STOP 




Statement 


Purpose: 


Stops execution of a program and returns to 
command level. 


Versions: 


Cassette Disk Advanced Compiler 



Format: STOP 

Remarks: STOP statements can be used anywhere in a program 
to stop execution. When BASIC encounters a STOP 
statement, it displays the following message: 

Break in nnnnn 

at which nnnnn is the line number where the STOP 
occurred. 

Unlike the END statement, the STOP statement does 
not close files. 

BASIC always returns to command level after it 
executes a STOP. You can resume execution of the 
program by issuing a CONT command. See "CONT 
Command." 
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STOP 

Statement 

Example: This example calculates the value of TEMP, then 

stops. While the program is stopped, you can check 
the value of TEMP. Then you can use CONT to 
resume program execution at line 40. 

10 INPUT A, B 

20 TEMP= A*B 

30 STOP 

40 FINAL = TEMP+200: PRINT FINAL 

RUN 

? 26, 2.1 

Break in 30 

PRINT TEMP 

54.6 
CONT 

254.6 
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STR$ 

Function 

Purpose: Returns a string representation of the value of x. 
Versions: Cassette Disk Advanced Compiler 

Format: v$ = STR$(jc) 

Remarks: x is any numeric expression. 

If x is positive, the string returned by STR$ contains 
a leading blank (the space reserved for the plus sign). 
For example: 

? STR$(321); LEN(STR$(321 ) ) 
321 4 

The VAL function is complementary to STR$. See 
"VAL Function." 

Example: This example branches to different sections of the 
program according to the number of digits in a 
number that is entered. The number of digits are 
counted by using STR$ to convert the number to a 
string; then the program branches, based on the 
length of the string. 

10 INPUT "TYPE A NUMBER";N 

20 ON LEN(STR$(N))-1 GOSUB 30,100,200,300 
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STRIG 

Statement and Function 



Purpose: Returns the status of the joystick buttons (triggers). 
Versions: Cassette Disk Advanced Compiler 



Format: As a statement: 
STRIG ON 
STRIG OFF 

As a function: 



Remarks: 



v = STRIG(rc) 



is a numeric expression in the range to 3. It 
affects the value returned by the function as 
follows: 

Returns -1 if button Al was pressed 
since the last STRIG(0) function call; 
returns if not. 

1 Returns -1 if button Al is currently 
pressed; returns if not. 

2 Returns -1 if button Bl was pressed 
since the last STRIG(2) function call; 
returns if not. 

3 Returns -1 if button Bl is currently 
pressed; returns if not. 
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STRIG 

Statement and Function 

In Advanced BASIC and the BASIC 

Compiler, you can read four buttons from the 
joysticks. The additional values for n are: 

4 Returns -1 if button A2 was pressed 
since the last STRIG (4) function call; 
returns if not. 

5 Returns - 1 if button A2 is currently 
pressed; returns if not. 

6 Returns -1 if button B2 was pressed 
since the last STRIG(6) function call; 
returns if not. 

7 Returns -1 if button B2 is currently 
pressed; returns if not. 

STRIG ON must be executed before any STRIG(rc) 
function calls can be made. After STRIG ON, every 
time the program starts a new statement, BASIC 
checks to see if a button was pressed. 

If STRIG is OFF, no testing takes place. 

See the next entry, "STRIG(rc) Statement," for 
enhancements to the STRIG function in Advanced 
BASIC. 
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STRIG(n) 
Statement 



Purpose: Enables and disables trapping of the joystick 
buttons. 

Versions: Cassette Disk Advanced Compiler 



Format: 



STRIG(rc) ON 
STRIG(rc) OFF 
STRIG(rt) STOP 



Remarks: 



can be 0, 2, 4, or 6 and indicates the button 
to be trapped as follows: 



button Al 
button Bl 
button A2 
button B2 



STRIG(ft) ON must be executed to enable trapping 
by the ON STRIG(rc) statement. See "ON STRIG 
Statement." After STRIG(«) ON, every time the 
program starts a new statement, BASIC checks to 
see if the specified button has been pressed. 

If STRIG(rt) OFF is executed, no testing or trapping 
takes place. Even if the button is pressed, the event 
is not remembered. 

If a STRIG(«) STOP statement is executed, no 
trapping takes place. However, if the button is 
pressed it is remembered so that an immediate trap 
takes place when STRIG(«) ON is executed. 
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STRINGS 

Function 



Purpose: Returns a string length n whose characters all have 
ASCII code m or the first character of x$. 

Versions: Cassette Disk Advanced Compiler 



Format: v$ = STRING$(«,m) 
v$ = STRINGS (n,x$) 
Remarks: 

n, m are in the range to 255. 

x$ is any string expression. 

Example: This example repeats an ASCII value of 45 to print a 
string of hyphens. 

10 X$ = STRING$(10,45) 

20 PRINT X$ "MONTHLY REPORT" X$ 

RUN 

MONTHLY REPORT 



This example repeats the first character of the string 
"ABCD". 



10 X$="ABCD" 

20 Y$=STRING$(10,X$) 

30 PRINT Y$ 

RUN 

AAAAAAAAAA 
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SWAP 

Statement 

Purpose: Exchanges the values of two variables. 
Versions: Cassette Disk Advanced Compiler 



Format: 
Remarks: 



SWAP variablel, variable2 



variablel, variable2 

are the names of two variables or array 
elements. 

Any type variable can be swapped (integer, 
single-precision, double-precision, string), but the 
two variables must be of the same type or a Type 
mismatch error results. 

Example: In this example, after line 30 is executed, A$ has the 
value " ALL " and B$ has the value " ONE ". 



10 A$=" ONE " : B$=" ALL 

20 PRINT A$;C$;B$ 

30 SWAP A$, B$ 

40 PRINT A$;C$;B$ 

RUN 

ONE FOR ALL 

ALL FOR ONE 



: C$="F0R" 
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SYSTEM 
Command 



Purpose: Exits BASIC and returns to DOS. 

Versions: Cassette Disk Advanced Compiler 



Format: SYSTEM 

Remarks: SYSTEM closes all files before it returns to DOS. 
Your BASIC program is lost. 

If you entered BASIC through a batch file from 
DOS, the SYSTEM command returns you to the 
batch file, which continues executing at the next 
statement. 
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TAB 

Function 



Purpose: Tabs to position n. 
Versions: Cassette Disk 



Advanced Compiler 



Format: PRINT TAB(«) 

Remarks: n must be in the range 1 to 255. 

If the current print position is already beyond space 
n, TAB goes to position n on the next line. Space 1 
is the leftmost position, and the rightmost position is 
the defined WIDTH. 

TAB can be used only in PRINT, LPRINT, and 

PRINT # statements. 

If the TAB function is at the end of the list of data 
items, BASIC does not add a carriage return, as 
though the TAB function had an implied semicolon 
after it. 

Example: TAB is used in the following example to cause the 
information on the screen to line up in columns. 



10 PRINT "NAME" TAB(25) "AMOUNT" 

20 READ A$,B$ 

30 PRINT A$ TAB(25) B$ 

40 DATA "L. M. JACOBS" , "$25.00" 

RUN 

NAME AMOUNT 



PRINT 



L. M. JACOBS 



$25 
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TAN 
Function 



Purpose: Returns the trigonometric tangent of x. 
Versions: Cassette Disk Advanced Compiler 



Format: v = TAN(jc) 

Remarks: 

x is the angle in radians. To convert degrees to 

radians, multiply by PI/ 180, where 
PI=3. 141593. 

In BASIC 2.0 and later releases, you can have this 
calculation performed in double-precision by 
specifying /D in the BASIC command line when 
BASIC is initially loaded. See "Options in the 
BASIC Command" in the BASIC Handbook. 

Example: This example calculates the tangent of 45 degrees. 

10 PI=3. 141593 
20 DEGREES=45 

30 PRINT TAN(DEGREES*PI/180) 
RUN 
1 
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TIMES 

Variable and Statement 



Purpose: Sets or retrieves the current time. 

Versions: Cassette Disk Advanced Compiler 

Format: As a variable: 

v$ = TIMES 

As a statement: 

TIMES = x$ 

Remarks: For the variable (v$ = TIMES): 

The current time is returned as an 8-character string. 
The string is of the form hh:mm:ss, where hh is the 
hour (00 to 23), mm is the minutes (00 to 59), and 
ss is the seconds (00 to 59). (You may have set the 
time in DOS before you invoked BASIC.) 

For the statement (TIME$ = x$): 

The current time is set. x$ is a string expression 
indicating the time to be set. x$ can be given in one 
of the following forms: 

hh Set the hour in the range to 23. 

Minutes and seconds default to 00. 

hh:mm Set the hour and minutes. Minutes must 

be in the range to 59. Seconds default 
to 00. 

hh:mm:ss Set the hour, minutes, and seconds. 

Seconds must be in the range to 59. 
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TIME$ 

Variable and Statement 

A leading zero can be omitted from any of the above 
values, but you must include at least one digit. For 
example, if you want to set the time as a half hour 
after midnight, you can enter 

TIME$ = "0:30" 

but not 

TIME$ = ":30" 

If any of the values are out of range, an Illegal 
function call error is issued. The previous time is 
retained. If x$ is not a valid string, a Type mismatch 
error results. 

Example: The following program continuously displays the 
time on the screen. 

10 CLS 

29 LOCATE 10 s 15 

30 PRINT TIME$ 
40 GOTO 20 
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TIMER 

Function 



Purpose: Returns a single-precision number representing the 
number of seconds elapsed since midnight or a 
system reset. (For BASIC 2.0 and later releases.) 



Versions: Cassette 



Disk Advanced Compiler 



Format: v=TIMER 

Remarks: Fractional seconds are calculated to the nearest 
degree possible. TIMER is a read-only function. 

Example: This example illustrates how TIMER resets after 

midnight. Values may be slightly different for your 
system. 



10 TIME$="23:59:59" 

20 FOR 1=1 TO 20 

30 PRINT "TIME$= ";TIME$; 

40 NEXT 

RUN 



TIMER=";TIMER 



TIME$= 23:59:59 TIMER= 86399.06 
TIME$= 23:59:59 TIMER= 86399.11 
TIME$= 23:59:59 TIMER= 86399.18 



TIME$= 


24 


00 


00 


TIMER= 





TIME$= 


00 


00 


00 


TIMER= 


.05 


TIME$= 


00 


00 


00 


TIMER= 


.16 


TIME$= 


00 


00 


00 


TIMER= 


.21 
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TRON and TROFF 
Commands 



Purpose: Traces the execution of program statements. 
Versions: Cassette Disk Advanced Compiler 

Format: TRON 
TROFF 

Remarks: As an aid in debugging, the TRON command (which 
can be entered from within a program or in direct 
mode) enables a trace flag that prints each line 
number of the program as it is executed. The 
numbers appear enclosed in square brackets. The 
trace is turned off by the TROFF command. 

Example: This example uses TRON and TROFF to trace 

execution of a loop. The numbers in brackets are 
line numbers; the numbers not in brackets at the end 
of each line are the values of J, K, and L, which are 
printed by the program. 

10 K=10 

20 FOR 1=1 TO 2 

30 L=K + 10 

40 PRINT J;K;L 

50 K=K+10 

60 NEXT 

70 END 

TRON 

RUN 

[10][20][30][40] 10 20 

[50][60][30][40] 20 30 

[50][60][70] 

TROFF 
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USR 

Function 



Purpose: Calls the indicated assembly language subroutine 
with the argument arg. 

Versions: Cassette Disk Advanced Compiler 

Format: v = USR[n](arg) 

Remarks: 

n is an integer in the range 0-9 and corresponds 

to the digit supplied with the DEF USR 
statement for the desired routine. If n is 
omitted, USR0 is assumed. See "DEF USR 
Statement." 

arg is any numeric expression or string variable 

that is the argument to the assembly language 
subroutine. If the subroutine does not require 
an argument, arg must still be supplied as a 
dummy argument. 

The CALL statement is another way to interface 
with assembly language subroutines. See "CALL 
Statement." and also Appendix B, "Assembly 
Language Subroutines," for more information. 

When the USR function is called, register AL 
contains a value that specifies the type of argument 
supplied. The value in AL will be one of the 
following: 
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USR 

Function 

Value in AL Type of Argument 

2 2-byte integer (twos complement) 

3 String 

4 Single-precision number 
8 Double-precision number 



If the argument is a string, the DX register points to 
the 3-byte string descriptor. See Appendix B, 
"Assembly Language Subroutines," under "How 
BASIC Interfaces with Assembly Language 
Subroutines" for information on the string 
descriptor. 

If the argument is a number and not a string, the 
value of the argument is placed in the Floating Point 
Accumulator (FAC), which is an 8-byte area in 
BASIC'S data space. In this case, the BX register 
contains the offset within the BASIC data space to 
the fifth byte of the 8-byte FAC. For the following 
examples, assume that the FAC is in bytes hex 49F 
through hex 4A6; that is, BX contains hex 4 A3: 

If the argument is an integer: 

• Hex 4A4 contains the upper 8 bits of the 
argument. 

• Hex 4A3 contains the lower 8 bits of the 
argument. 

If the argument is a single-precision number: 

• Hex 4A6 contains the exponent minus 128, and 
the binary point is to the left of the most 
significant bit of the mantissa. Hex 4A5 contains 
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USR 

Function 



the highest 7 bits of the mantissa with the leading 
1 suppressed (implied). Bit 7 is the sign of the 
number (0 = positive; 1 = negative). 

• Hex 4A4 contains the middle 8 bits of the 
mantissa. 

• Hex 4A3 contains the lowest 8 bits of the 
mantissa. 

If the argument is a double-precision number: 

• Hex 4A3 through hex 4A6 are the same as 
described under single-precision floating-point 
number in the preceding paragraph. 

• Hex 49F through Hex 4A2 contain 4 more bytes 
of the mantissa (hex 49F contains the lowest 8 
bits). 

Usually, the value returned by a USR function is the 
same type (integer, string, single-precision, or 
double-precision) as the argument that was passed to 
it. However, a numerical argument of the function, 
regardless of its type, can be forced to an integer 
value by calling the FRCINT routine to get the 
integer equivalent of the argument placed into 
register BX. 

If the value being returned by the function is to be an 
integer, place the resulting value into the BX register. 
Then make a call to MAKINT just before the 
intersegment return. This passes the value back to 
BASIC by placing it into the FAC. 
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USR 

Function 

Example: The methods for accessing FRCINT and MAKINT 

are shown in the following example: 

10 DEFINT A-Z 

20 OPTION BASE 1 

30 X=0: Y=0: Z=0: 

40 DIM ARRAYUH14) 

50 Z = VARPTR(ARRAY(U) 

60 BLOAD"SUBRT.COM",Z 

70 DEF USR0= Z 

80 X = 5 

90 Y=USR0(X) 

100 PRINT Y 

The following assembly language subroutine has 
been loaded into an integer array. This subroutine 
doubles the argument passed and returns an integer 
result. 
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Function 






PAGE, 132 ; 




TITLE SUBRT.ASM 


» 


BLOAD header 


AAA 


SEGMENT PARA PUBLIC 'CODE' 




DB 0FDH 




DW 0,0 




DW TRAILER-HEADER 


AAA 

5 


ENDS 


RSEG 


SEGMENT AT 0F600H ;base of BASIC ROM 




ORG 3 ;offset to force intege 


FRCINT 


LABEL FAR 




ORG 7 ;offset to make integer 


MAKINT 


LABEL FAR 


RSEG 


ENDS 



CSEG SEGMENT BYTE PUBLIC 'CODE' 

HEADER EQU $ 

USRPRG PROC FAR ;entry point 

;cal! FRCINT and force argument 

;in FAC into [BX] 

DB 9AH 

DW FRCINT ;offset 

DW 0F600H ;segment id 

ADD BX,BX ;[BX]=[BX]*2 

;call MAKINT and put integer result 

;in [BX] into FAC 

DB 9AH 

DW MAKINT ;offset 

DW 0F600H ;segment id 

; intersegment return 



USRPRG 

TRAILER 

CSEG 



RET 

ENDP 

EQU 

ENDS 

END 
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USR 

Function 

Note: FRCINT and MAKINT perform 
intersegment returns. Make sure that the calls to 
FRCINT and MAKINT are defined by a FAR 
procedure. 
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VAL 

Function 

Purpose: Returns the numerical value of string x$. 
Versions: Cassette Disk Advanced Compiler 

Format: v = VAL(x#) 

Remarks: x$ is a string expression. 

The VAL function strips blanks, tabs, and line feeds 
from the argument string to determine the result. 
For example, 

VAL(" -3") 

returns -3. 

If the first characters of x$ are not numeric, 
VAL(;c#) returns (zero). 

See "STR$ Function" for numeric to string 
conversion. 

Example: In this example, VAL is used to extract the house 
number from an address. 

PRINT VALC'3408 SHERWOOD BLVD.") 
3408 
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VARPTR 

Function 



Purpose: Returns the offset to the current segment of memory 
of the variable. 



Versions: Cassette Disk 



Advanced Compiler 



Format: v = VARPTR (variable) 
Remarks: 



variable is the name of a numeric or string 
variable or array element in your 
program. A value must be assigned to 
variable before the call to VARPTR, or 
an Illegal function call error results. 

VARPTR returns an offset in the range to 65535. 
This number is the offset into BASIC'S data segment 
of the first byte of data identified with variable. The 
format of this data is described in Appendix B, 
Memory Information, in the BASIC Handbook, 
under "How Variables Are Stored." 

Note: All simple variables should be assigned 
before calling VARPTR for an array, because 
arrays will be relocated whenever a new simple 
variable is assigned. 

VARPTR is usually used to get the offset of a 
variable or array to BASIC'S data segment so it can 
be used to access assembly language subroutines and 
pass variables or arrays to them. 
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VARPTR 

Function 

Example: This example uses VARPTR to get the data from a 
variable. In line 30, P gets the address of the data. 
Integer data is stored in two bytes, with the less 
significant byte first. The actual value stored at 
location P is calculated in line 40. The bytes are 
read with the PEEK function, and the second byte is 
multiplied by 256 because it contains the high-order 
bits. 

10 DEFINT A-Z 

20 DATA1=500 

30 P=VARPTR(DATA1) 

40 V=PEEK(P) + 256*PEEK(P+1) 

50 PRINT V 
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VARPTR$ 

Function 



Purpose: Returns a character form of the offset of a variable 
in memory. It is primarily for use with PLAY and 
DRAW in programs that will be compiled. 



Versions: Cassette 



Disk Advanced Compiler 



Format: 
Remarks: 



v$ = VARPTR$ (variable) 



variable is the name of a variable in the program. 

Note: All simple variables should be assigned 
before calling VARPTR$ for an array element, 
because arrays are relocated whenever a new 
simple variable is assigned. 

VARPTR$ returns a 3-byte string in the form: 



Byte0 


Bytel 


Byte 2 


type 


low byte of 
variable address 


high byte of 
variable address 



type indicates the variable type: 

2 integer 

3 string 

4 single-precision 
8 double-precision 
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VARPTR$ 

Function 

The returned value is the same as: 

CHR$(type)+MKI$(VARPTR( variable)) 

You can use VARPTR$ to indicate a variable name 
in the command string for PLAY or DRAW. For 
example: 

Method One Alternative Method 

PLAY "XA$;" PLAY "X"+VARPTR$(A$) 
PLAY "0=I;" PLAY "0="+VARPTR$(I) 
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VIEW 
Statement 



Purpose: Defines a rectangular subset of the screen onto 
which WINDOW and WINDOW contents are 
mapped. (For BASIC 2.0 and later releases.) 

Versions: Cassette Disk Advanced Compiler 

*** 

Graphics mode only. 

Format: VIEW [ [SCREEN] \{xl,yl)- (x2,y2) [,[color] 
[XboundaryWW ] 

Remarks: 

(xl,yl)-(x2,y2) 

are the upper-left (xl,yl) and the 
lower-right (x2,y2) coordinates of 
the viewport defined. The x and y 
coordinates must be within the 
actual limits of the screen or an 
Illegal function call error occurs. 
For more information, see 
"Specifying Coordinates" under 
"Graphics Modes" in Chapter 3 
of the BASIC Handbook. 

color lets you fill the defined viewport 

with color. If color is omitted, the 
viewport is not filled, color is an 
integer expression that chooses an 
attribute from the attribute range 
for the current screen mode. In 
medium resolution, the color is the 
current one for that attribute as 
defined by the COLOR 
statement. Four attributes (0-3) 
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VIEW 

Statement 



boundary 



are available in medium 
resolution; in high resolution, two 
attributes (0-1) are available. 
Zero (0) is always the attribute 
for the background. The default 
foreground attribute is always the 
maximum attribute for that screen 
mode: 3 in medium resolution; 1 
in high resolution. 

lets you draw a boundary line 
around the viewport (if space is 
available). If boundary is omitted, 
no boundary is drawn, boundary is 
an integer expression in the range 
described in color. 



It is important to note that VIEW sorts the x and y 
argument pairs, placing the smaller values for x and y 
first. For example: 

VIEW (100,100)-(5,5) 

becomes: 

VIEW (5,5)-(100,100) 

Another example: 

VIEW (310,100)-(200,150) 

becomes: 

VIEW (200,100)-(310,150) 

All possible pairings of x and y are valid. The only 
restriction is that xl cannot equal x2 and >>7 cannot 
equal ^2. The viewport cannot be larger than the 
viewing surface. 
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VIEW 

Statement 

If the SCREEN argument is omitted, all points 
plotted are relative to the viewport. That is, xl and 
yl are added to the x and y coordinates before 
plotting the point on the screen. For example, if: 

10 VIEW (10,10)-(200,100) 

is executed, the point plotted by PSET (0,0), 3 is at 
the actual screen location 10,10. 

If the SCREEN argument is included, all points 
plotted are absolute and can be inside or outside the 
screen limits. However, only those points within the 
viewport limits are visible. For example if: 

10 VIEW SCREEN ( 10 ,10 ) - ( 200 ,100) 

is executed, the point plotted by PSET (0,0), 3 does 
not appear on the screen because 0,0 is outside the 
viewport. PSET (10, 10), 3 is within the viewport 
and places the point in the upper-left corner. 

VIEW with no arguments defines the entire screen as 
the viewport. 

You can define multiple viewports, but only one 
viewport can be active at a time. RUN and change 
in SCREEN attributes disable the viewports. 

VIEW used with WINDOW allows you to scale 
images. See the second example. See also 
"WINDOW Statement." 

Note: When VIEW is used, the CLS statement 
clears only the current viewport. To clear the 
entire screen, you must use VIEW to disable the 
viewports, and then use CLS to clear the screen. 
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VIEW 

Statement 

With viewports, CLS does not move the cursor to 
the home position. Use Ctrl-Home to send the 
cursor home and clear the screen. 

Examples: The following example defines four viewports: 

10 SCREEN 1 : VIEWrCLS: KEY OFF 
20 VIEW (1,1 )-(151 ,91 ) , ,1 
30 VIEW (165,1 )-(315,91 ) , ,2 
40 VIEW (1 ,105)-(151 ,195) , ,2 

50 VIEW (165,105)-(315,195),,1 

60 LOCATE 2,4:PRINT "Viewport 1" 

70 LOCATE 2,25:PRINT "Viewport 2" 

80 LOCATE 15,4:PRINT "Viewport 3" 

90 LOCATE 15,25:PRINT "Viewport 4" 

100 VIEW (1,1)-(151,91):G0SUB 1000 

200 VIEW (165,1)-(315,91):G0SUB 2000 

300 VIEW (1,105)-(151,195):GOSUB 3000 

400 VIEW (165,105)-(315,195):GOSUB 4000 

900 END 

1000 CIRCLE (65, 50), 30, 2 

1010 'Draw a circle in first viewport 

1020 RETURN 

2000 LINE (45,50)-(90,75),l,B 

2010 'Draw a box in second viewport 

2020 RETURN 

3000 FOR D=0 TO 360:DRAW "ta=d;nu20" : NEXT 

3010 'Draw spokes in third viewport 

3020 RETURN 

4000 PSET(60,50),2:DRAW "el5;fl5;130" 

4010 'Draw a triangle in fourth viewport 

4020 RETURN 
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VIEW 

Statement 

This example demonstrates scaling with VIEW. 

10 KEY OFF:CLS:SCREEN 1,0:COLOR 0,0 

20 WINDOW SCREEN(320,0)-(0,200) 

30 GOTO 80 

40 C=l 

50 CIRCLE (160, 100), 60, C,,, 5/18 

60 CIRCLE (160,100),60,C,,,1 

70 RETURN 

80 GOSUB 460: FOR 1=1 TO 1500:NEXT I: CLS 

90 VIEW (1,1)t(160,90),,2:GOSUB 40 

100 GOTO 100 
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WAIT 

Statement 



Purpose: Suspends program execution while monitoring the 
status of a machine input port. 



Advanced Compiler 



Versions: 


Cassette Disk 




*** *** 


Format: 


WAIT port, n[,m] 


Remarks: 





port is the port number, in the range to 65535. 

n, m are integer expressions in the range to 255. 

See the IBM Personal Computer Technical Reference 
for a description of valid port numbers (I/O 
addresses). 

The WAIT statement suspends program execution 
until a specified machine input port develops a 
specified bit pattern. 

The data read at the port is XORed with the integer 
expression m and then ANDed with n. If the result is 
zero, BASIC loops back and reads the data at the 
port again. If the result is nonzero, execution 
continues with the next statement. If m is omitted, it 
is assumed to be zero. 

The WAIT statement lets you test one or more bit 
positions on an input port. You can test the bit 
position for either a 1 or a 0. The bit positions to be 
tested are specified by setting 1 's in those positions 
in n. If you do not specify m, the input port bits are 
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WAIT 

Statement 

tested for l's. If you specify m, a 1 in any bit 
position in m (for which there is a 1 bit in n) causes 
WAIT to test for a for that input bit. 

When executed, the WAIT statement loops, testing 
those input bits specified by l's in n. If any one of 
those bits is 1 (or if the corresponding bit in m is 
1), then the program continues with the next 
statement. Thus WAIT does not wait for an entire 
pattern of bits to appear, but only for one of them to 
occur. 

Note: It is possible to enter an infinite loop with 
the WAIT statement. You can do a Ctrl-Break 
or a System Reset to exit the loop. 

Example: To suspend program execution until port 32 receives 
a 1 bit in the second bit position: 

100 WAIT 32,2 
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WHILE and WEND 

Statements 



Purpose: Executes a series of statements in a loop as long as a 
given condition is true. 



Versions: Cassette Disk 
Format: WHILE expression 



Advanced Compiler 



Remarks: 



(loop statements) 



WEND 



expression 



is any numeric expression. 



If expression is true (not zero), loop statements 
execute until the WEND statement is encountered. 
BASIC then returns to the WHILE statement and 
checks expression. If expression is still true, the 
process is repeated. If it is not true, execution 
resumes with the statement following the WEND 
statement. 

WHILE- WEND loops can be nested to any level. 
Each WEND matches the most recent WHILE. An 
unmatched WHILE statement causes a WHILE 
without WEND error, and an unmatched WEND 
statement causes a WEND without WHILE error. 
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WHILE and WEND 
Statements 

Example: The following example sorts the elements of the 

array A into alphabetical order. A was defined with 
J elements. 

10 'bubble sort array A 

20 FLIPS=1 'force first pass thru loop 

30 WHILE FLIPS 

40 FLIPS=0 

50 FOR 1=1 TO J-l 

60 IF A(I)>A(I+1) THEN 

SWAP A(I),A(I+1): FLIPS=1 
70 NEXT I 
80 WEND 
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WIDTH 

Statement 



Purpose: Sets the output line width in number of characters. 
After outputting the indicated number of characters, 
BASIC adds a carriage return. 



Versions: Cassette Disk 
Format: WIDTH size 



Advanced Compiler 



Remarks: 



WIDTH device, size 
WIDTH #filenum,size 



size is a numeric expression in the range to 

255. This is the new width. WIDTH is 
the same as WIDTH 1. 

device is a string expression for the device 
identifier. Valid devices are SCRN:, 
LPT1:, LPT2:, LPT3:, COM1:, or 
COM2:. 

filenum is a numeric expression in the range 1 to 
15. This is the number of a file opened to 
an output device. 

Depending on the device specified, the following 
actions are possible: 

WIDTH size or WIDTH "SCRN:" size 

Sets the screen width. Only 40- or 
80-column widths are allowed. WIDTH 
40 is not valid for the IBM Monochrome 
Display. 
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WIDTH 

Statement 

If the screen is in medium-resolution 
graphics mode (as occurs with a SCREEN 
1 statement), WIDTH 80 forces the 
screen into high resolution (as with a 
SCREEN 2 statement). The reverse if 
true when in high resolution. 

Note: Changing the screen width 
causes the screen to be cleared, and 
sets the border screen color to black. 

WIDTH device,size 

Is a deferred width assignment for the 
device. This form of width stores the new 
width value without changing the current 
width setting. A subsequent OPEN to the 
device will use this value for width while 
the file is open. The width does not 
change immediately if the device is already 
open. 

Note: LPRINT, LLIST, and 
LIST,"LPTn" do an implicit OPEN 
and are therefore affected by this 
statement. 

WIDTH #filenum,size 

The width of the device associated with 
filenum is immediately changed to the new 
size specified. This allows the width to be 
changed at will while the file is open. 
This form of WIDTH has meaning only 
for LPT1: in Cassette BASIC. Disk 
BASIC and Advanced BASIC also allow 
LPT2:, LPT3:, COM1:, and COM2:. 
Note that the number sign (#) is required. 
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WIDTH 

Statement 



Any value entered outside the ranges indicated 
results in an Illegal function call error. The previous 
value is retained. 

WIDTH has no effect for the keyboard (KYBD:) or 
cassette (CAS1:). 

The width for each printer defaults to 80 when 
BASIC is started. The maximum width for the IBM 
80 CPS Matrix Printer is 132. However, no error is 
returned for values between 132 and 255. 

It is up to you to set the appropriate physical width 
on your printer. Some printers are set by sending 
special codes; some have switches. For the IBM 80 
CPS Matrix Printer you should use LPRINT 
CHR$(15); to change to a condensed typestyle when 
printing at widths greater than 80. Use LPRINT 
CHR$(18); to return to normal. The IBM 80 CPS 
Matrix Printer is set up to automatically add a 
carriage return if you exceed the maximum line 
length. 

Specifying a width of 255 disables line folding. This 
has the effect of "infinite" width. WIDTH 255 is 
the default for communications files. 

Changing the width for a communications file does 
not change either the receive or the transmit buffer; 
it just causes BASIC to send a carriage return 
character after every size character. 

Changing screen mode affects screen width only 
when moving between SCREEN 2 and SCREEN 1 
or SCREEN 0. See "SCREEN Statement." 
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WIDTH 

Statement 

Example: In this example, line 10 stores a printer width of 75 
characters per line. Line 20 opens file #1 to the 
printer and sets the width to 75 for subsequent 
PRINT #1,... statements. Line 6020 changes the 
current printer width to 40 characters per line. 
Notice that the WIDTH value must come before the 
OPEN statement. 

10 WIDTH "LPT1 : ",75 

20 OPEN "LPT1:" FOR OUTPUT AS #1 



6020 WIDTH #1,40 

These examples change screen mode and width. 

SCREEN 1,0 'Set to med-res color graphics 

WIDTH 80 'Go to hi-res graphics 

WIDTH 40 'Go back to medium res 

SCREEN 0,1 'Go to 40x25 text color mode 

WIDTH 80 'Go to 80x25 text color mode 
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WINDOW 

Statement 



Purpose: Redefines the coordinates of the viewport. (For 
BASIC 2.0 and later releases.) 

Versions: Cassette Disk Advanced Compiler 

*** 



Graphics mode only. 

Format: WINDOW [ [SCREEN] (xl,yl)- (x2,y2) ] 

(xl,yl),(x2,y2) 

are programmer-defined coordinates 
called world coordinates. These 
coordinates are single-precision, 
floating-point numbers. They define the 
world coordinate space that will be 
mapped into the the physical coordinate 
space, as defined by the VIEW 
statement. See "VIEW Statement." 

WINDOW allows you to draw objects in space 
("world coordinate system") and not be bounded by 
the limits of the screen ("physical coordinate 
system"). This is done by specifying the world 
coordinate pairs (xl,yl) and (x2,y2). BASIC then 
converts world coordinate pairs for subsequent 
display within the viewport. To make this 
transformation from world space to the physical 
space of the screen, BASIC must know what portion 
of the unbounded world coordinate space contains 
the information you want to be displayed. This 
rectangular region in the world coordinate space is 
called a window. 
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WINDOW 

Statement 

In the physical coordinate system, if you run the 
following: 

NEW 
SCREEN 2 

the screen appears with standard coordinates as: 

r 



0,0 



320,0 



639,0 



y increases 



\k 



0,199 



320,100 



320,199 



639,199 



When the SCREEN attribute is omitted, the screen is 
viewed in true Cartesian coordinates. For example, 
given: 

WINDOW (-1,-1)~(1,1) 

the screen appears as: 



■i,i 



0,1 



A\ 



\1/ 



y increases 



0,0 



y decreases 
1,-1 0,-1 



1,1 



1,-1 



Note that the y coordinate is inverted so that (xl,yl) 
is the lower-left coordinate and (x2,y2) is the 
upper-right coordinate. 
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WINDOW 

Statement 



When the SCREEN attribute is included, the 
coordinates are not inverted so that (xl,yl) is the 
upper-left coordinate and (x2,y2) is the lower-right 
coordinate. For example: 

WINDOW SCREEN (-1 ,-l)-(l ,1) 
defines the screen to look like this: 



■1,-1 



0,-1 



1,-1 



/N 



y decreases 



0,0 



y increases 
1,1 0,1 



1,1 



It is important to note that WINDOW sorts the x and 
y argument pairs, placing the smaller values for x and 
y first. For example: 

WINDOW (100,100)-(5,5) 

becomes: 

WINDOW (5,5)-(100,100) 

Another example: 

WINDOW (-4,4)-(4,-4) 

becomes: 

WINDOW (-4,-4)-(4,4) 
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WINDOW 

Statement 

All possible pairings of x and y are valid. The only 
restriction is that xl cannot equal x2 and j>7 cannot 
equal y2. 

WINDOW also allows you to "zoom" and "pan." 
Using a window with coordinates larger than an 
image displays the entire image, but the image is 
small and blank spaces appear on the sides of the 
screen; Choosing window coordinates smaller than 
an image forces clipping and allows only a portion of 
the image to be displayed and magnified. By 
specifying small and large window sizes, you can 
zoom in until an object occupies the entire screen, or 
you can zoom out until the image is just a spot on the 
screen. 

RUN, SCREEN, and WINDOW with no attributes 
disable any WINDOW definitions and return the 
screen to physical coordinates. 

Examples: The following example shows clipping using 
WINDOW. 

10 SCREEN 2:CLS 

20 WINDOW (-6,-6)-(6,6) 

30 CIRCLE (4, 4), 5,1 

40 'the circle is large and only part is visible 

50 WINDOW (-100,-100)-(100,100) 

60 CIRCLE (4, 4), 5,1 'the circle is \/ery small 

70 END 
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WINDOW 

Statement 

The following example shows the effect of zooming 
using WINDOW. 

10 KEY OFF:CLS:SCREEN 1,0 

20 ' 

30 GOTO 160 

40 ' = = = = ================= 

50 'procedure display 

60 ' 

70 LINE (X,0)-(-X.0),,,&HAA00 'create x axis 

80 LINE (0,X)-(0,-X),,,&HAA00 'create y axis 

90 ' 

100 CIRCLE (X/2,X/2),R 'circle has radius r 

110 FOR P = l TO 50.-NEXT P 'delay loop 

120 ' 

130 RETURN 

140 '==================== 

150 ' 

160 X=1000:WINDOW (-X,-X)-(X,X) :R=20 

170 'create a graph with large coord range 

180 GOSUB 50:FOR P=l TO 1000:NEXT P:CLS 

190 ' 

200 X=60:WINDOW (-X,-X)-(X,X) :R=20 

210 'smaller coord range increase circle size 

220 GOSUB 50:FOR P=l TO 1000:NEXT P:CLS 

230 ' 

240 X=100:WINDOW (-5,-5)-(X,X) :R=20 

250 'modify window to show only portion of axes 

260 GOSUB 50: FOR P=l TO 1000:NEXT P:CLS 

270 ' 

280 PRINT " an example":PRINT" . of zooming.. 1 

290 FOR P=l TO 1500:NEXT P 

300 CLS:T=-50:U=100:X=U 

310 FOR 1=1 TO 45 

320 T=T + 1:U=U - 1:X=X-1:R=20 

330 WINDOW (T,T)-(U,U):CLS:GOSUB 50 

340 NEXT I 

350 END 
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WRITE 
Statement 



Purpose: Outputs data to the screen. 

Versions: Cassette Disk Advanced Compiler 



Format: WRITE [list of expressions] 
Remarks: 

list of expressions 

is a list of numeric and/or string 
expressions, separated by commas or 
semicolons. 

If the list of expressions is omitted, a blank line is 
displayed. If the list of expressions is included, the 
values of the expressions are displayed on the screen. 

When the values of the expressions are displayed, 
each item is separated from the one before it by a 
comma. Strings are delimited by quotation marks. 
After the last item in the list is printed, BASIC adds 
a carriage return/line feed. 

WRITE is similar to PRINT. The difference 
between WRITE and PRINT is that WRITE inserts 
commas between the items as they are displayed and 
delimits strings with quotation marks. Also, positive 
numbers are not preceded by blanks. 



375 



WRITE 

Statement 

Example: The following example shows how WRITE displays 
numeric and string values. 

10 A=80: B=90: C$=". THAT'S ALL" 
?a wrttf a r rt 

RUN 

80,90, ".THAT'S ALL" 
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WRITE # 
Statement 



Purpose: Writes data to a sequential file. 

Versions: Cassette Disk Advanced Compiler 



Format: WRITE ttfilenum, list of expressions 

Remarks: 

filenum is the number under which the file 

was opened for output. 

list of expressions 

is a list of string and/or numeric 
expressions, separated by commas or 
semicolons. 

The difference between WRITE # and PRINT # is 
that WRITE # inserts commas between the items as 
they are written and delimits strings with quotation 
marks. Therefore, it is not necessary for you to put 
explicit delimiters in the list. Also, WRITE # does 
not put a blank in front of a positive number. A 
carriage return/line feed sequence is inserted after 
the last item in the list is written. 

Example: Let A$= ".CAMERA" and B$= ".93604-1". The 
statement: 

WRITE #1,A$,B$ 

writes the following image to the file. 

".CAMERA"/ 1 . 93604-1" 
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WRITE* 

Statement 

A subsequent INPUT # statement: 

INPUT #1,A$,B$ 

inputs ".CAMERA" to A$ and ".93604-1" to B$. 



378 



Appendixes 



Contents 

Appendix A. Error Messages A-3 

Appendix B. Assembly Language Subroutines B-l 

Reference Material B-l 

Deciding Where In Memory To Load Your 

Subroutines B-2 

DOS-Loaded Subroutines for BASIC B-2 

Features B-3 

Considerations B-3 

Inside the BASIC Data Segment B-3 

Features B-4 

Considerations B-4 

Beyond the BASIC Data Segment B-5 

Features B-5 

Considerations B-5 

How to Load and Call Your Assembly Language 
Subroutines B-6 

Poking or Assigning a Subroutine into Memory B-6 

Features B-6 

Considerations B-7 

BLOADing the Subroutine from a File B-10 

Features B- 1 1 

Considerations B-l 1 

A Sample Subroutine B-l 2 

Sample Subroutine Explanation B-l 3 

Loading the Subroutine as a Resident Extension of 
DOS B-19 

Features B-19 

Considerations B-19 



A-l 



How BASIC Interfaces with Assembly 

Language Subroutines B-24 

The CALL Statement B-26 

Memory Map B-29 

Appendix C. Communications C-l 

Opening a Communications File C-l 

Communication I/O C-l 

GET and PUT for Communications Files . C-2 

I/O Functions C-2 

INPUTS Function C-3 

A Sample Program C-3 

Notes on the Program C-5 

Operation of Control Signals C-6 

Control of Output Signals with OPEN C-6 

Use of Input Control Signals C-6 

Testing for Modem Control Signals C-7 

Direct Control of Output Control Signals .... C-8 
Communication Errors C-9 

Appendix D. ASCII Character Codes D-l 

Extended Codes D-6 

Appendix E. Scan Codes E-l 



A-2 



Appendix A. Error Messages 



If BASIC detects an error that causes a program to stop 
running, an error message is displayed. You can trap 
and test errors in a BASIC program using the ON 
ERROR statement and the ERR and ERL variables. 
For complete explanations of ON ERROR, ERR, ERL, 
ERDEV, and ERDEV$, see those entries in this 
manual. 

This appendix lists alphabetically all BASIC error 
messages with an explanation of each message, as well 
as some suggestions for recovering from errors. The 
separate BASIC Quick Reference lists all messages in 
order by their associated numbers. 

Number Message 

73 Advanced feature 

Your program specified an Advanced BASIC 
feature while you are using Disk BASIC. 

Start Advanced BASIC and rerun your 
program. 

54 Bad file mode 

You tried to use PUT or GET with a 
sequential or a closed file; or to execute an 
OPEN with a file mode other than input, 
output, append, or random. 

Make sure the OPEN statement was entered 
and executed properly. GET and PUT 
require a random file. 

This error also occurs if you try to merge a 
file that is not in ASCII format. In this case, 
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make sure you are merging the right file. If 
necessary, load the program and save it 
again, using the A option. 

64 Bad file name 

An invalid form was used for the filename 
with KILL, NAME, or FILES. 

Check "Naming Files" in Chapter 3 of the 
BASIC Handbook for information on valid 
filenames, and correct the filename in error. 

52 Bad file number 

A statement specified a file number of a file 
that is not open, or the file number is out of 
the range of possible file numbers specified 
at initialization. Or, the device name in the 
file specification is too long or invalid, or the 
filename is too long or invalid. 

Make sure the file you wanted was opened 
and entered correctly in the statement. 
Check to see that you have a valid file 
specification. See "Naming Files" in 
Chapter 3 of the BASIC Handbook for 
information on file specifications. 

63 Bad record number 

In a PUT or GET (file) statement, the record 
number is either equal to zero or greater than 
the maximum allowed (32767 in BASIC 
versions earlier than 2.0). GET and PUT 
have subsequently been enhanced to allow 
record numbers in the range 1 to 16,777,215 
to accommodate large files with short record 
numbers. 

Correct the PUT or GET statement to use a 
valid record number. 

17 Can't continue 

You tried to use CONT to continue a 
program that: 
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• Halted because of an error 

• Was changed during a break in execution 

• Does not exist 

Make sure the program is loaded, and use 
RUN to run it. 

— Can't continue after SHELL 

You shelled to a child process that 
terminated and remained resident. A child 
process cannot remain resident because it 
prevents BASIC from recovering its 
workspace, causing the program to halt. 

69 Communication buffer overflow 

A communication input statement was 
executed, but the input buffer was already 
full. 

Use an ON ERROR statement to retry the 
input when this condition occurs. 
Subsequent inputs try to clear this fault 
unless characters continue to be received 
faster than the program can process them. If 
this happens there are several possible 
solutions: 

• Increase the size of the communications 
buffer using the /C: option when you 
start BASIC. 

• Implement a "hand-shaking" protocol 
with the other computer to tell it to stop 
sending long enough for you to catch up. 
See the example in Appendix C, 

' ' Communications . ' ' 

• Use a lower baud rate to transmit and 
receive. 



A-5 



25 Device fault 

A hardware error indication was returned by 
an interface adapter. In Cassette BASIC, 
this occurs only when a fault status is 
returned from the printer interface adapter. 

This message can also occur when data is 
transmitted to a communications file. In this 
case, it indicates that one or more of the 
signals being tested (specified on the OPEN 
"COM... statement) were not found in the 
specified period of time. 

57 Device I/O error 

An error occurred on a device I/O operation. 
DOS cannot recover from the error. 

When receiving communications data, this 
error can occur from overrun, framing, 
break, or parity errors. For data with 7 or 
less bits, the eighth bit is turned on in the 
byte in error. 

24 Device timeout 

BASIC did not receive information from an 
input/output device within a predetermined 
amount of time. In Cassette BASIC, this 
occurs only while the program is trying to 
read from the cassette or write to the printer. 

For communications files, this message 
indicates that one or more of the signals 
tested with OPEN "COM... was not found in 
the specified period of time. 

Retry the operation. 

68 Device unavailable 

You tried to open a file to a device that is not 
installed. Either you do not have the 
hardware to support the device (such as 
printer adapters for a second or third 
printer), or you have disabled the device. 
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(For example, you may have used /C:0 in the 
BASIC command line to start Disk BASIC. 
That would disable communications devices.) 

Make sure the device is installed correctly. If 
necessary, Return to DOS where you can 
reenter the BASIC command line. 

66 Direct statement in file 

A direct statement was encountered during a 
loading or chaining operation to an ASCII 
format file. The LOAD or CHAIN is 
terminated. 

The ASCII file should consist only of 
statements preceded by line numbers. This 
error may occur because of a line feed 
character in the input stream. 

61 Disk full 

All disk storage space is in use. Files are 
closed when this error occurs. 

If there are files on the disk that you no 
longer need, erase them or use a new disk. 
Then retry the operation or rerun the 
program. 

72 Disk media error 

The controller attachment card detected a 
hardware or media fault. Usually this means 
that the disk has gone bad. 

Copy any existing files to a new disk and 
reformat the bad disk. If there are problems 
during reformatting, the disk should be 
discarded. 
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71 Disk not ready 

The disk drive door is open or a disk is not in 
the drive. 

Place the correct disk in the drive and 
continue the program. 

70 Disk write protect 

You tried to write to a disk that is 
write-protected. 

Make sure you are using the right disk. If so, 
remove the write-protect tab; then retry the 
operation. 

This error can also occur because of a 
hardware failure. 

1 1 Division by zero 

In an expression, you tried to divide by zero, 
or you tried to raise zero to a negative power. 

It is not necessary to correct this condition, 
because the program continues running. 
Machine infinity with the sign of the number 
being divided is the result of the division; or, 
positive machine infinity is the result of the 
exponentiation. This error cannot be trapped 
using ON ERROR. 

10 Duplicate definition 

You tried to define the size of the same array 
twice. This can happen in one of several 
ways: 

• The same array is defined in two DIM 
statements. 

• The program encounters a DIM 
statement for an array after the default 
dimension of 10 is established for that 
array. 
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• The program sees an OPTION BASE 
statement after an array has been 
dimensioned, either by a DIM statement 
or by default. 

Move the OPTION BASE statement to make 
sure it is executed before you use any arrays; 
or, fix the program so each array is defined 
only once. 

50 Field overflow 

A FIELD statement tried to allocate more 
bytes for the record length of a random file 
than were specified in the OPEN statement. 
Or, the end of the FIELD buffer was 
encountered during sequential I/O (PRINT 
#, WRITE #, INPUT #) to a random file. 

Check the OPEN statement and the FIELD 
statement to make sure they correspond. If 
you are doing sequential I/O to a random 
file, make sure that the length of the data 
read or written does not exceed the record 
length of the random file. 

58 File already exists 

The filename specified in a NAME command 
duplicates an existing filename on the disk. 

Retry the NAME command using a different 
name. 

55 File already open 

You tried to open a file for sequential output 
or append, and the file is already open; or, 
you tried to use KILL on a file that is open. 

Make sure you execute only one OPEN to a 
file if you are writing to it sequentially. 
Close a file before you use KILL. 



A-9 



53 File not found 

A LOAD, KILL, NAME, FILES, or OPEN 
references a file that does not exist on the 
disk in the specified drive. 

Verify that the correct disk is in the drive 
specified, and that the file specification was 
entered correctly. Then retry the operation. 

26 FOR without NEXT 

A FOR was encountered without a matching 
NEXT. That is, a FOR loop was active 
when the physical end of the program was 
reached. 



1 2 Illegal direct 

You tried to enter a statement in direct mode 
that is invalid in that mode (such as DEF 

FN). 

The statement should be entered as part of a 
program line. 

5 Illegal function call 

A parameter that is out of range was passed 
to a system function. The error can also 
occur as the result of: 

• Using a negative or an unreasonably large 
subscript 

• Trying to raise a negative number to a 
power that is not an integer 

• Calling a USR function before defining 
the starting address with DEF USR 

• Using a negative record number on GET 
or PUT (file) 
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• Using an improper argument to a function 
or statement 

• Trying to list or edit a protected BASIC 
program 

• Trying to delete line numbers that don't 
exist 

See "BASIC Commands, Statements, and 
Functions" in this manual for information 
about the particular statement or function. 

— Incorrect DOS version 

The command you just entered requires a 
different version of DOS from the one you 
are running. 

62 Input past end 

This is an end-of-file error. An input 
statement was executed for a null (empty) 
file, or it was executed after all the data in a 
sequential file was already input. 

To avoid this error, use the EOF function to 
detect the end of a file. 

This error also occurs if you try to read from 
a file that was opened for output or append. 
If you want to read from a sequential output 
(or append) file, you must close it and open 
it again for input. 

51 Internal error 

An internal malfunction occurred in BASIC. 

Recopy your disk. Check the hardware, 
following instructions in the Guide to 
Operations and retry the operation. If the 
error recurs, note the conditions under which 
the message appeared and notify the place of 
purchase. 
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23 Line buffer overflow 

You tried to enter a line with too many 
characters. 

If there are several statements on the line, 
move some of them to the next line. Also, 
use string variables instead of constants 
where possible. 

22 Missing operand 

An expression contains an operator, such as 
* or OR, with no operand following it. 

Make sure you include all the required 
operands in the expression. 

1 NEXT without FOR 

The NEXT statement doesn't have a 
corresponding FOR statement. It may be 
that a variable in the NEXT statement does 
not correspond to any previously executed 
and unmatched FOR statement variable. 

19 No RESUME 

The program branched to an active 
error-trapping routine as a result of an error 
condition or an ERROR statement. The 
routine does not have a RESUME statement. 
(The physical end of the program was 
encountered in the error trapping routine.) 

Be sure to include RESUME in your 
error-trapping routine to continue program 
execution. You may want to add an ON 
ERROR GOTO statement to your 
error-trapping routine so BASIC displays the 
message for any untrapped error. 

4 Out of data 

A READ statement tried to read more data 
than is in the DATA statements. 
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7 Out of memory 

A program is too large, has too many FOR 
loops or GOSUBs, too many variables, 
expressions that are too complicated, or 
complex painting. 

You can use CLEAR at the beginning of 
your program to set aside more stack space 
or memory area. 

27 Out of paper 

The printer is out of paper or is not switched 
on. 

Make sure that the power is on, verify that 
the printer is properly connected, insert 
paper if necessary; then, continue the 
program. 

14 Out of string space 

BASIC allocates string space dynamically 
until it runs out of memory. This message 
means that string variables caused BASIC to 
exceed the amount of free memory remaining 
after housecleaning. 

6 Overflow 

A number is too large to be represented in 
BASIC'S number format. Integer overflow 
causes execution to stop. Otherwise, 
machine infinity with the appropriate sign is 
supplied as the result, and execution 
continues. Integer overflow is the only type 
of overflow that can be trapped. 

To correct integer overflow, use smaller 
numbers, or change to single- or 
double-precision variables. 
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Note: If a number is too small to be 
represented in BASIC'S number format, 
there is an underflow condition. If this 
occurs, the result is zero and execution 
continues without an error. 

75 Path/file access error 

During an OPEN, RENAME, MKDIR, 
CHDIR, or RMDIR operation, you tried to 
use a path or filename to an inaccessible file. 
For example, you tried to open a directory or 
volume identifier; you tried to open a read 
only file for writing; or you tried to remove 
the current directory. The operation is not 
completed. 

76 Path not found 

During an OPEN, MKDIR, CHDIR, or 
RMDIR operation, DOS was unable to find 
the path specified. The operation is not 
completed. 

74 Rename across disks 

You tried to rename a file, but you specified 
the wrong disk. 

The rename operation is not performed. 

When you use RENAME, the drive you 
specify must be the same for the old filename 
and the new filename. The exception to this 
is when the DOS ASSIGN command is 
active. The drive name can be different, but 
the same physical device must be specified. 
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20 RESUME without error 

The program encountered a RESUME 
statement without having trapped an error. 
The error-trapping routine should be entered 
only when an error occurs or an ERROR 
statement is executed. 

You probably need to include a STOP or 
END statement before the error-trapping 
routine to prevent the program from "falling 
into" the error-trapping code. 

3 RETURN without GOSUB 

A RETURN statement does not have a 
previous unmatched GOSUB statement. 

Correct the program. You probably need to 
put a STOP or END statement before the 
subroutine so the program doesn't "fall 
into" the subroutine code. 

1 6 String formula too complex 

A string expression is too long or too 
complex. Break it into shorter expressions. 

1 5 String too long 

You tried to create a string more than 255 
characters long. Break it into shorter strings. 

9 Subscript out of range 

You used an array element either with a 
subscript that is outside the dimensions of 
the array, or with the wrong number of 
subscripts. 

Check the usage of the array variable. You 
may have put a subscript on a variable that is 
not an array, or you may have coded a 
built-in function incorrectly. 



A-15 



2 Syntax error 

A line contains an incorrect sequence of 
characters, such as an unmatched 
parenthesis, a misspelled command or 
statement, or incorrect punctuation. 

Or, the data in a DATA statement doesn't 
match the type (numeric or string) of the 
variable in a READ statement. 

Or, a reserved word has been used as a 
variable name. See Chapter 3 of the BASIC 
Handbook for a list of reserved words. 

When this error occurs, the BASIC Program 
Editor automatically displays the line in 
error. Correct the line or the program. 

67 Too many files 

You tried to create a new file (using SAVE 
or OPEN) when all directory entries on the 
disk are full, or when the file specification is 
invalid. 

If the file specification is correct, use a new 
formatted disk and retry the operation. 

13 Type mismatch 

You gave a string value where a numeric 
value was expected, or you had a numeric 
value in place of a string value. This error 
may also be caused by trying to SWAP 
variables of different types, such as single- 
and double-precision. 

8 Undefined line number 

A line that doesn't exist in the program was 
referred to in a command or statement. 

Check the line numbers in your program, and 
use the correct line number. 
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1 8 Undefined user function 

You called a function before defining it with 
the DEF FN statement. 

Make sure the program executes the DEF 
FN statement before you use the function. 

— Unprintable error 

A specific error message is not available for 
the error condition that exists. This is 
usually caused by an ERROR statement with 
an undefined error code. 

Check your program to make sure you 
handle all error codes. 

30 WEND without WHILE 

A WEND was encountered before a 
matching WHILE was executed. 

Correct the program so that there is a 
WHILE for each WEND. 

29 WHILE without WEND 

A WHILE statement does not have a 
matching WEND. That is, a WHILE was 
still active when the physical end of the 
program was reached. 

Correct the program so that each WHILE 
has a corresponding WEND. 

— You cannot SHELL to Basic 

BASIC cannot be run as a child process. 
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Appendix B. Assembly Language 
Subroutines 



This appendix describes how BASIC interfaces with 
assembly language subroutines. In particular, it 
describes: 

• Where in memory to locate your assembly language 
subroutines 

• How BASIC interfaces with assembly language 
subroutines 

• How to load and call your assembly language 
subroutines 

This appendix is intended to be used by an experienced 
assembly language programmer. 



Reference Material 

The following publications contain related material that 
you may find useful. 

Rector, Russell and Alexy, George. The 8086 
Book. Osborne/McGraw-Hill, Berkeley, California, 
1980, (includes the 8088) 

Intel Corporation Literature Department. The 8086 
Family User's Manual, 9800722. 3065 Bowers 
Avenue, Santa Clara, CA 95051. 

IBM Corporation Personal Computer library. 
Macro Assembler. Boca Raton, FL 33432. 

IBM Corporation Personal Computer library. 
Technical Reference. Boca Raton, FL 33432. 
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Deciding Where In Memory To Load 
Your Subroutines 

BASIC normally uses all memory available from the 
starting location of its data area up to a maximum of 
64K bytes. This area contains your BASIC program 
and data* along with the interpreter work area and 
BASIC'S stack. You can allocate memory space for 
assembly language subroutines either inside or outside 
this BASIC 64K data segment. Where you put your 
assembly language subroutine depends on three items: 

• Total amount of memory in your computer 

• Size of your BASIC program 

• Characteristics of your assembly language program 

There are many methods for installing assembly 
language subroutines. We recommend these three 
places for storing them: 

• As a resident part of DOS that is loaded before 
BASIC is invoked 

• In an integer array within BASIC'S data segment 

• Beyond BASIC'S data segment 

DOS-Loaded Subroutines for BASIC 

This is the recommended method for interfacing an 
assembly language subroutine from BASIC because it 
insures compatibility of your programs with DOS and 
BASIC now and in the future. It also reduces the 
margin for error when interfacing your subroutines. It 
does require additional planning in coding your 
subroutines. A sample subroutine later in this chapter 
shows you how this is done. 
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Features 



This method allows for multisegment subroutines, 
(up to 64K) and for nonself-relocating subroutines 
that would be impossible for BLOAD or DATA 
statements to handle properly. 

It safely makes the subroutine a resident part of 
DOS with no need to "hide" the subroutine from 
BASIC nor to reserve or protect space for the 
subroutine from BASIC or DOS. 



Considerations 



DOS-loaded subroutines remain resident once they 
are loaded. Only rebooting the system removes the 
subroutine. In addition to this, multiple copies of 
the subroutine can become resident if it is invoked 
several times. This is best handled by defining a call 
at the end of your application that reboots your 
machine by calling the BIOS boot code and, hence, 
reinitializes all of memory. 

There is some overhead involved when invoking 
subroutines that remain resident through INT 27. 
Along with the resident portion of your code, you 
will have a copy of the DOS environment, which is a 
minimum of 128 bytes, and a PSP (program 
segment prefix), which is 256 bytes. 



Inside the BASIC Data Segment 

For relatively short assembly language programs, 
loading your subroutines into an integer array within 
BASIC is the easiest and safest way to store them. 



B-3 



Features 



Because you are working within BASIC'S data 
segment, it is not necessary to address an external 
segment for your subroutine with the DEF SEG 
statement. 

By loading the subroutine inside BASIC'S data 
segment and into a data area allocated and 
maintained by BASIC, there is no danger of your 
program stepping onto critical space inside or 
outside BASIC, or code outside BASIC stepping on 
your data. 



Considerations 



If your BASIC application uses most of the 
available data space within BASIC'S data segment, 
this is not the best method since you will be using 
additional data space by assigning the subroutine to 
an integer array. 

In certain configurations, this method is your only 
option. You must calculate how much free memory 
you have in your machine before you choose your 
method. Factors you must consider are: the size of 
DOS, the size of BASIC, whether your application 
needs Disk BASIC or Advanced BASIC, and the 
size of any resident routines such as MODE, 
PRINT, or GRAPHICS. 

The sizes of DOS and BASIC vary depending on the 
level of code you are using. On a small system, 
when you invoke BASIC, there may not be any free 
space in the top of memory. In this case, use the 
integer array method. 

The assembler code must be self -relocatable; that is, 
it must not contain any references to a paragraph 
number of a segment whose value depends on where 
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the subroutine was loaded. This means that all 
offsets must be expressed in relative terms so that 
your subroutine is able to resolve all references 
within itself. 



Beyond the BASIC Data Segment 

You must have at least 128K in your system to use this 
procedure. Also, you may be required to do some of 
your own memory management to ensure the integrity 
of your program. For these reasons, loading 
subroutines beyond the BASIC data segment is the 
least desirable method for assembly language interface. 



Features 



You do not have to use space within BASIC'S data 
segment for your routines. 

With systems that have a large amount of memory, 
you can load subroutines that are too large to fit 
within the BASIC data segment. 



Considerations 

When you load a subroutine outside BASIC'S data 
segment, you are responsible for managing the area of 
memory occupied by your subroutine. To ensure the 
integrity of your program: 

• You can restrict the size of BASIC'S total 
addressable space with the CLEAR statement or the 
/M: switch from the BASIC command line. This 
ensures that none of BASIC'S data overlays your 
subroutine. 

• You must calculate within your program the new 
segment ID, which you will pass to the DEF SEG 
statement. 
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When calculating the amount of available memory, 
you must allow for any routines that are resident at 
the time your subroutine is called (PRINT, MODE, 
or a virtual disk program, for example). 



How to Load and Call Your Assembly 
Language Subroutines 



The following are offered as examples of how assembly 
language subroutines are loaded into memory. There 
are essentially three ways: 

• Poking or assigning it into memory from your 
BASIC program. 

• BLOADing it from a file on disk or cassette. 

• Loading it from a file on disk as a resident part of 
DOS. 



Poking or Assigning a Subroutine into Memory 

You can POKE or assign assembly language 
subroutines directly into memory from your program. 
In this way the subroutine actually becomes a part of 
your BASIC program. 



Features 



You do not need an assembler to use this method. 

All code is contained in one file. You need not be 
concerned with the creation and maintenance of two 
or more separate files. 
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Considerations 



Coding each statement of your subroutine in 
hexadecimal can become a very tedious and 
error-prone procedure. This method is most useful 
for very short subroutines. 

If you poke your subroutine into a memory area 
outside of BASIC'S data segment, you must perform 
any memory management necessary to reserve or 
protect subroutine space from BASIC or DOS, in 
order to ensure the integrity of your program. 



Assigning a Subroutine into Memory 

This is the procedure you use to assign machine code to 
an integer array and invoke the subroutine: 

1 . Determine the machine code for your subroutine. 
See "DEBUG" in Disk Operating System (DOS) 
manual under the "Assemble" option. 

2. Dimension an integer array to the size you need. 
Remember, an integer uses 2 bytes of memory, so 
the size of your array is one-half the number of 
bytes in your subroutine. 

There are several reasons for using an integer array 
(2 bytes per element) instead of a single-precision 
(4 bytes per element) or a double-precision array (8 
bytes per element) . When you assign the subroutine 
to an integer array, you will never leave more than 1 
byte of memory unused; with a double-precision 
array, you could waste 7 bytes. A fundamental 
reason for the integer array method is that you 
perform WORD assignment to the array elements 
rather than byte assignment, and a WORD happens 
to be 2 bytes. It would be easy to make a mistake if 
you were assigning four words to each array element 
since the CPU in the system expects to see the 
machine code in a low-byte- high-byte format. The 
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example that follows shows how the machine code 
in the assignment statements is switched from the 
order of the bytes as they appear in the assembled 
listing. 

3. Define all scalars to be used in the application. 
After an array is dimensioned, any scalar created 
pushes or relocates the array farther up in memory. 
See the memory map in Appendix D for related 
information. 

4. Assign the machine language code to the array 
elements, one word at a time. Remember that your 
system reads bytes expecting the low byte first, so 
store your data low-byte, high-byte. 

5. Determine the offset of the subroutine within 
BASIC'S data segment by using the VARPTR 
function. 

6. Invoke the subroutine with the CALL statement or 
the USR function. 
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Example: 

10 DEFINT A-Z: OPTION BASE 1: DIM ARRAY (3) 



20 DATA &HCD55 

30 DATA &H5D05 

40 

50 DATA &H90CB 



REM 55H Push BP 
REM CD05H INT 5 
REM 5DH POP BP 
REM 90H NOP 



7a pnp t - i to -5 . pr/\n ARRAY ^ I ^ : NEXT I 

80 PRINT "This is an example of how " 

90 PRINT "a BASIC routine can cause " 

100 PRINT "a hard copy to be dumped " 

110 PRINT "to a printer by using the " 

120 PRINT "shift-print screen function " 

130 PRINT "called via an assembly language " 

140 PRINT "subroutine that is built into " 

150 PRINT "a BASIC integer array" 

160 SUBRT = VARPTR(ARRAY(D): CALL SUBRT 

Notice that the data statement reads data into the 
array a WORD at a time. The assembled listing would 
list the bytes in the order that they appear in the 
commented section of the program, yet the program 
switches the order of the bytes in the words as they 
are assigned to the array elements since the format of 
a word is low-byte, high-byte. 

It is a recommended practice to always put VARPTR 
and CALL in the same line so CALL is never 
performed without locating the array containing the 
subroutine. 



Poking a Subroutine into Memory 

This next example uses the same assembly language 
subroutine, but the BASIC POKE statement is used to 
POKE the bytes into the array. The POKE statement 
takes care of the byte order for you, so you do not 
have to the order of the bytes as they would appear in 
an assembled listing. 
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10 DEFINT A-Z:OPTION BASE 1 :P=0: 1=0: J=0: 
DIM ARRAY(3) 

20 DATA &H55 :REM 55H Push BP 
30 DATA &HCD, &H05 :REM CD05H INT 5 
40 DATA &H5D :REM 5DH POP BP 
50 DATA &HCB :REM CBH RET FAR 
60 :REM 90H NOP 

70 P=VARPTR(ARRAY(l)):FOR 1=0 TO 4:READ J 

POKE(P+I),J:NEXT T 
80 PRINT "This is a 
90 PRINT "a BASIC r 
100 PRINT "a hard c 
110 PRINT "to a pri 
120 PRINT "shift-pr 
130 PRINT "called v 
140 PRINT "subrouti 
150 PRINT "a BASIC 
160 SUBRT = VARPTR( 



n example of how " 
outine can cause " 
opy to be dumped " 
nter by using the " 
int screen function " 
ia an assembly language 
ne that is built into " 
integer array" 
ARRAY(D): CALL SUBRT 



POKE can be used to put data anywhere in memory. 
To POKE this routine into another segment, line 
70 would be: 



DEF SEG = SEGMENT 
P0KE(I,J): NEXT 



FOR 1=0 TO 4: READ J 



Because the subroutine is placed in an area other than 
BASIC'S data segment, there is no VARPTR reference 
to obtain the offset of the subroutine. 



BLOADing the Subroutine from a File 



You use the BASIC BLOAD command to load a 
memory image file directly into memory. The file can 
be a memory image file that was saved using the 
BASIC BSAVE command; or it can be an assembly 
language subroutine that was assembled with a 
BLOAD header, linked and converted to a .COM file 
using EXE2BIN. See Disk Operating System (the 
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DOS manual) for information on EXE2BIN. 
Assembly language subroutines can be BLOADed into 
an integer array or beyond BASIC'S data segment. 



Features 



When a subroutine is loaded into BASIC'S data 
segment, BASIC performs all memory 
management. You are not responsible for the 
integrity of your subroutine once it is under the 
control of BASIC. 

By loading subroutines outside of BASIC'S data 
segment it is possible to construct a program larger 
than BASIC'S normal 64K limit. 



Considerations 



• An assembler is necessary in order to use this 
method. 

• For an assembly language subroutine to be 
BLOADed into memory, it must appear to have 
been created by BSAVE. This is done by including 
a 7 -byte BSAVE header that is linked as the first 
segment of the subroutine. These 7 bytes function 
as a loader that BLOAD looks at and then 
discards. The beginning of your routine in memory 
is the first byte following this header. 

The example that follows shows how a subroutine is 
BLOADed into an integer array within BASIC and 
then is called from BASIC. The subroutine adds the 
contents of the first and second parameters and puts 
the results into the third parameter. 

This also illustrates self-relocating code. A 
step-by-step explanation of the procedure follows. 
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1 . Assemble and link your subroutine. 

2. Convert the file to a .COM file via EXE2BIN. 

3. From BASIC, dimension an integer array to the 
size needed. (Remember, size of the array 
subscript is 1/2 the number of bytes in your 
subroutine.) 

4. Declare all scalars used in your application. This 
includes any parameters you may pass on through 
the CALL statement. 

5. Obtain the offset of the array within BASIC'S data 
space using the VARPTR function. 

6. BLOAD the subroutine into the array. 

7. Call the subroutine with this offset. 



A Sample Subroutine 



The function of this subroutine is to add the contents 
of the first and second parameters and put the results 
into the third parameter. It shows a unique way to 
pass parameters to a subroutine that is located inside 
an integer array. Parameters are passed by storing 
them as elements of an array into which the subroutine 
has been BLOADed. 

The comments inserted in the program listing are 
intended to help you understand the most important 
points of the operation and structure of this 
subroutine. A more detailed analysis follows the 
listing. 
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AAAA SEGMENT PARA PUBLIC 'CODE' 

DB 0FDH ;BSAVE id 

DW 0,0 

DW TRAILER-HEADER ;Module size 
AAAA ENDS 
PAGE 

BASDATSEG SEGMENT BYTE PUBLIC 'CODE' 
ASSUME CS : bASUA'l Stla ,L)b : bAbUA I SEG 
HEADER EQU $ ;Start of memory image 
SUBRT PROC FAR 

NOP ;Adjusts for proper 
boundary also allows 
replacement by 0CCH, 
the INT 3, which is 
DEBUG's breakpoint. 
CALL SKI ;This pushes offset 
; of 'BASE' into stack 

BASE: ;local workarea 

WORKA DW ;First input parameter, 
; BASIC'S ARRAY(3) 

WORKB DW ;Second input parameter,, 
; BASIC'S ARRAY(4) 

;Result, BASIC'S ARRAY(5) 
BX ;Now BX knows at what 
offset into BASI r ' r 
data space is 'BASE ' 
AX. WORKA - RASFTRX1 :Rp+ 1st. parm 
AX,W0kKb - BASE[BX] ;Add ^nd parm 

to ACC 
WORKC-BASE[BX] s AX ;Pass to 3rd parm 



5L.nu wi ihciiiuij iniaye 



WORKC 


DW ;R 


SKIP: 

3 


POP 


» 


MOV 




ADD 


3 


MOV 




RET 


SUBRT 


ENDP 


to mi m mi 1 


BASDATSEG ENDS 




END 
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Sample Subroutine Explanation 

This example generates a header that looks as if it 
were created by BSAVE. It must be linked to the 
beginning of the load module by using a segment name 
that comes first alphabetically. 

AAAA SEGMENT PARA PUBLIC 'CODE' 

DB 0FDH ;BSAVE id 

DW 0,0 

DW TRAILER-HEADER ;Module size 
AAAA ENDS 

PAGE 

This value for module size, divided by 2, is the value 
to be substituted for N in the BASIC program below. 

The BYTE alignment of the following SEGMENT 
statement is needed so the memory image will be 
loaded as the next byte following the dummy BSAVE 
header with no alignment padding bytes in between. 

BASDATSEG SEGMENT BYTE PUBLIC 'CODE' 

This code is to be loaded into a BASIC integer array 
in BASIC'S data segment. The offsets shown by the 
assembler listing are relative to the start of the 
subroutine, not to the start of BASIC'S data segment, 
which is what CS and DS really point to. The 
subroutine must do its own offset fixup by finding 
where in BASIC'S data segment it is loaded, and then 
modifying the assembler's offsets by this base amount. 
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HEADER 
SUBRT 



ASSUME 
EQU 
PROC 
NOP 



FAR 





CALL 


SKI 


BASE: 






WORKA 


DW 


;Firs 


WORKB 


DW 


;Seco 


WORKC 


DW 


;Resu 


SKIP: 
> 


POP 


BX 


5 


MOV 


AX, 1 




ADD 


AX ,' 



CS : BASDATSEG ,DS : BASDATSEG 
;Start of memory image 

;Adjusts for proper 
boundary al so al 1 ows 
replacement by 0CCH, 
the INT 3, which is 
DEBUG's breakpoint. 
;This pushes offset 
of 'BASE' into stack 
;local workarea 
t input parameter, 
BASIC'S ARRAY(3) 
nd input parameter, 
BASIC'S ARRAY(4) 
It, BASIC'S ARRAY(5) 
;Now BX knows at what 
offset into BASIC'S 
data space is 'BASE ' 
WORKA - BASE[BX] ;Get 1st 
WORKB - BASELBX] ;Add 2nd 
to ACC 



parm 
parm 



Note how local storage is to be addressed. Adding 
the BX performs the needed self-relocation, changing 
local offsets to offsets from DS (BASIC'S data 
segment). 

MOV WORKC-BASE[BX],AX ;Pass to 3rd parm 

RET 
SUBRT ENDP 

TRAILER EQII $ ;Fnd of memorv imaae 

BASDATSEG ENDS 
END 
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The calling routine from BASIC would be as follows: 

10 OPTION BASE 1 

20 DEFINT A-Z 

30'Define scalars before DIM 

40 SUBRT = 

50 DIM ARRAY(10) 

60'Load subroutine into array 

70 BLOAD "SUB2.BL0", SUBRT 

80 'Pass parameters into array 

90 ARRAY(3)=2: ARRAY(4)=3 

100' Find where array starts 

110 SUBRT=VARPTR(ARRAY(1)) 

120'Parms are in the array 

130 CALL SUBRT 

140'Display result 

150 PRINT ARRAY(5) 

The next example performs the same function as the 
previous example. However, parameters are passed by 
putting variables names in the parenthesized list in the 
CALL statement. 

10 OPTION BASE 1 

20'Define scalars before DIM 

30 SUBRT%=0: PARMC%=0 

40 DIM ARRAY%(12) 

50' Find start of array 

60 SUBRT%=VARPTR(ARRAY%(1)) 

70 'Load routine into array 

80 BLOAD "SUB1.BL0", SUBRT% 

90'Pass parms to subroutine 

100 PARMA% = 2: PARMB% = 3 

110'Locate subroutine 

120 SUBRT% = VARPTR(ARRAY%(1)) 

130 'Parms in CALL 

140 CALL SUBRT%(PARMA%, PARMB%, PARMC%) 

150'Display results 

160 PRINT PARMC% 
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The subroutine named SUB1.BLO is as follows: 



PARM STRUC 

SAVEBP DW 

RETOFF DW 

RETSEG DW 

PARMC DW 

PARi v iB DW 

PARMA DW 

PARM ENDS 



Description of parameter list 
Saves BASIC'S BP register 
Offset of where to RET to 
Segment to return to 
Offset to third parameter 
Offset to second parameter' 
Offset to first parameter 



AAA SEGMENT PARA 

DB 0FDH 

DW 0,0 

DW TRAILER-HEADER 
AAA ENDS 



;BSAVE ID 
;Module size 



BASDATSEG SEGMENT BYTE PUBLIC 'CODE' 

ASSUME CS:BASDATSEG,DS:BASDATSEG 



;Start of memory image 



debugging, can be 
laced by 0CCH (INT 3) 
ch is the DEBUG 
akpoint 

ve BASIC'S BP register 
Set addressability to 
parm area on stack 
PARMA ;Get offset to parml 

;Get value of parml 
PARMB ;Get offset to parm2 

• l\AA \/ a 1 1 10 nf pa v*m9 +*n a r r 

PARMC ;Get ofset to parm3 

;Pass result to parm3 
store BASIC'S BP 
turn to BASIC, 
owing away the 3 parms 



HEADER 


EQU 


$ ;Sta 


SUBRT 


PROC 


FAR 


> 


NOP 


;For 
rep 
w h i 
bre 




PUSH 


BP ;Sa 




MOV 


BP,SP ; 


5 


MOV 


SI,[BP]. 




MOV 


AX,[SI] 




MOV 


SI,[BP]. 




MOV 


AX, [SI] 




MOV 


DI,[BP]. 




MOV 


[DI],AX 




POP 


BP ;Re 


5 


RET 


6 ;Re 

thr 


SUBRT 


ENDP 




TRAILER 


EQU 


$ ;En 


BASDATASEG ENDS 




END 





;End of memory image 



Load your assembly language program into this 
external data area using the BASIC BLOAD 
command. You can also POKE the subroutine into 
memory. Load your subroutine beginning at offset 
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of the first paragraph after the BASIC data segment. 
This segment ID can be calculated by adding to the 
value of BASIC'S segment ID the maximum number of 
paragraphs that BASIC can address. 

BASIC is not necessarily located in the same segment 
on every machine, so calculate where to BLOAD your 
subroutine using the following procedure: 

• Set the current segment at segment with the 
DEF SEG statement. The segment ID of BASIC'S 
data segment is located in low memory, segment 0, 
offsets &H5 10 and &H5 1 1 . This memory area is 
mapped in the IBM Personal Computer Technical 
Reference manual in Section 3 under "Low 
Memory Maps." 

• PEEK at these two values and assign the result to a 
variable. 

• Add to this value the maximum number of 
paragraphs that BASIC will address. By default, 
this is 4096 or &H1000. This value can be 
modified by the CLEAR statement or the /M: 
switch. 

• Declare this value as your new segment ID with the 
DEF SEG statement. 

• BLOAD your subroutine at offset into this 
segment. 

The BASIC code for this is: 

10 DEF SEG = 'Look at low memory 

20 'Get segment ID 

30 V = PEEK(&H510) + (256. * PEEK(&H511)) 

40 SEGID = V + &H1000'Add 4096 paragraphs 

50 'Def seg to next segment after basic 

60 DEF SEG = SEGID 

70 'Load into this segment at offset 

80 BLOAD "SUBR0UT.COM" , 
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Loading the Subroutine as a Resident 
Extension of DOS 



You can load your assembled subroutine under DOS 
as though it were a command. BASIC can then call 
your subroutine when it is needed. 



Features 



The area containing your subroutine is protected 
by DOS. You are not required to perform any 
memory management to ensure the integrity of 
your program. 

Your assembled code need not be self-relocatable. 

You can load very large modules with this method. 
DOS allocates the portion of memory necessary to 
load itself and its extensions before it allocates 
space to BASIC. 

Because your subroutine remains resident when 
loaded by DOS, you can write one subroutine that 
can be used by various programs. The subroutine 
need be loaded only once. 



Considerations 



An assembler is necessary in order to use this 
method. 

DOS-loaded subroutines remain resident until the 
system is rebooted. If memory space is critical, 
you must code your application so that a reboot is 
performed when the application completes. 
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The DOS-loaded module (your assembled subroutine) 
consists essentially of two parts: the BASIC 
subroutine and the loader portion. Invoke the module 
as a DOS external command (type the filename with 
no extension). The following steps must happen in the 
load portion of your assembly language subroutine: 

• Store in low memory the double-word vector 
pointing to the subroutine. 

• Tell DOS how much of the module is to remain 
resident (just the BASIC subroutine portion, not 
the loader portion). 

• Return to DOS through INT 27H, which leaves the 
subroutine resident. 

A problem with the DOS-loaded module is that you 
must let BASIC know where the subroutine is now 
that it has been loaded. A vector in the first 1 K of 
memory that is reserved for users can be selected. The 
intra-application communication area ( 1 6 bytes at 
&H4F0 - 4FF in segment 0) can also be used to 
contain the 4-byte vector that points to the 
subroutine. See the IBM Personal Computer Technical 
Reference in Section 3 under the "Low Memory 
Maps" tables. 

The loader should store both the offset and the 
segment ID of the subroutine in a fixed location in 
segment 0. BASIC can then execute a DEF SEG = 
and a PEEK at the 4 bytes following offset &H4F0 to 
find where the subroutine is. This is similar to finding 
the value of BASIC'S default DEF SEG mentioned 
earlier. 

To avoid multiple copies of the subroutine becoming 
resident, define a .BAT file that invokes the 
subroutine to load it and invokes BASIC and its 
application. Upon completion, the application should 
call the BIOS boot code to reboot the system and 
therefore avoid leaving the subroutine in memory. 
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The .BAT file should appear as follows: 

subroutine-name 

BASIC application-name 

The loader portion of the subroutine sets up the 
intra-application communication area pointer and 
leaves the subroutine resident: 

SEGZERO SEGMENT AT 

ORG 4F0H ;Intra-application 

; communication area 

C0MAREA_0FF DW ? ;Vector pointing to 

COMAREA_SEG DW ? permanent resident 

; BASIC subroutine. 
SEGZERO ENDS 



GRP 

AAAA 

AAAA 



GROUP AAAA,ZLOADER 



SEGMENT 'CODE 



ENDS 



;Identifies the start 

of load module 
;Forces class "code" 
to load before "data" 



PARA PUBLIC 'DATA' 
;Insert local data to be used by subroutine here 
SUBDAT ENDS 
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SUBSEG 


SEGMENT 


PARA PUBLIC 




ASSUME 


CS:SUBSEG 


SUBRT 


PROC 


FAR ;BAS 




PUSH 


BP ;Sav 




MOV 


BP,SP ;Get 



PUSH 



ES 



CODE 



entry point 
Save BASIC'S registers 
Get 

addressabil i ty 
to parms on stack 
;Save BASIC'S 
registers 





MOW 


/\v 

nA 


CIIDn/\T 
) ou uun i 




MOV 


ES 


,AX ;Set 


5 






addressabil i ty 


» 






to local data 


3 


ASSUME 


ES 


SUBDAT ;DS still points 
to BASIC'S data area 


;Insert 


the BASIC f 


subroutine here 




POP 


ES 


;Restore BASIC'S 




POP 


BP 


;Registers 


5 

5 


RET 


n 


;Return to BASIC, 
discard parms 
from stack 


SUBRT 


ENDP 






SUBSEG 


ENDS 







ZLOADER SEGMENT BYTE 'ZLOAD' 

ASSUME CS:ZLOADER,SS:ZSTACK 

; Stack not available 

; to subroutine 

ENDRES EQU $ ;End BASIC subroutine. 

The rest 

of this subroutine 
does not stay resident 

LOADER PROC FAR ;Entry from DOS 
PUSH ES ;Set up stack to 

; contain vector so 

XOR AX, AX ;'RET' will return 

to INT 27H 
instruction at 
offset in PSP. 
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PUSH 


AX 




MOV 


BYTE PTR ES:1,27H 

Change INT 20H 

to INT 27H at start 

of PSP 




XOR 


AX, AX ;Clear a register 




MOV 


ES,AX ;Set extra segment 


5 


ASSUME 


ES.SEGZERO 

;Seg reg points to 
low memory 




MOV 


COMAREA__OFF, OFFSET SUBRT 


J 




Pass offset to entry 


» 




point of subroutine 




MOV 


COMAREA-SEG,SEG SUBRT 


» 




Pass subroutine 


» 




segment 




MOV 


DX, OFFSET GRP:ENDRES+100H 
Pass offset of end 
of resident code. 
At exit, CS will 
point to the PSP 
which has the exit 
instruction 27H. 
This sets DX to the 
offset from the CS 
that is the end of 
t r"i e r e s i d e n L code. 




RET 


;Return to DOS, via 
INT 27H in PSP 
leaving subroutine 


J 




resident. 


LOADER 


ENDP 




ZLOADER 


ENDS 




ZSTACK 


SEGMENT 


PARA STACK 'STACK' 


s 


DB 


16 DUP ("STACK") 

;Stack used during 
procedure only 


ZSTACK 


ENDS 






END 


LOADER 



The subroutine with its loader is assembled and 
linked. It is then ready for execution as an .EXE 
external DOS command. 

Once the BASIC application is loaded, it can find the 
subroutine by: 
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20 DEFINT A-Z 

30 DEF SEG=0 'Look at low memory at 

40 'inter application communication area. 

50 SUBOFF=PEEK(&H4F0) + (256*PEEK(&H4FU) 

60 SUBSEG=PEEK(&H4F2)+(256*PEEK(&H4F3)) 

It can then call the subroutine by: 

100 DEF SEG = SUBSEG 

110 CALL SUBOFF(PARMA,PARMB,PARMC) 

120 DEF SEG 

When finished with execution, the application can 
reboot the system, thus removing the subroutine, by: 

1000 DEF SEG = &HF000: SUBOFF = &HFFF0: 

CALL SUBOFF 



How BASIC Interfaces with Assembly 
Language Subroutines 

BASIC provides two interfaces for calling assembly 
language subroutines from your application. They are 
the CALL statement and the USR function. The 
CALL statement is the recommended procedure and 
all examples use this interface. See "USR Function" 
in the BASIC Reference. 

When you invoke your subroutine the following is 
true: 

• At entry, the segment registers DS, ES, and SS are 
set to the same segment value, the segment ID of 
BASIC'S data segment. This is the default value 
for DEF SEG. 

• At entry, the CS register contains the segment ID 
of the latest value specified for DEF SEG. By 
default, this is BASIC 's segment ID. 

• At entry, the stack pointer register (SP) indicates 
that you have a minimum of eight words available 
on the stack for use by your subroutine. Other 
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space is provided on the stack for use by interrupts 
(such as TIMER) and DOS or BIOS calls invoked 
by the assembler subroutine. If your subroutine 
needs more stack space, create your own stack 
with a minimum of 1 28 bytes reserved for system 
usage above the requirements of the subroutine 
itself. Upon returning to BASIC, the stack 
segment (SS) and the stack pointer (SP) registers 
must have the same values as when the subroutine 
was called from BASIC. Care must be taken to 
preserve these values if you set up your own stack. 

If the input parameter is a string, the value passed is 
the offset in BASIC'S data segment of a 3-byte area 
called the string descriptor. 

Byte contains the length of the string (0 to 255) 

Byte 1 contains the lower 8 bits of the offset of the 
string in the string space area of BASIC'S 
data segment. 

Byte 2 contains the higher 8 bits of the offset of the 
string in the string space area of BASIC'S 
data segment. 

Warning: The subroutine must not change the 
contents of any of the 3 bytes of the string 
descriptor. 

The subroutine can change the content of the string 
itself, but not its length. 

If the subroutine changes a string, this may modify 
your program. The following example may change the 
string "TEXT" in the BASIC program. 

A$ = "TEXT" 
CALL SUBRT(A$) 

However, the next example does not change the 
program, because the string concatenation causes 
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BASIC to copy the string into the string space where it 
can be safely changed without affecting the original 
text. 

A$ = "BASIC" + "" 
CALL SUBRT(A$) 

To return from your subroutine, you must: 

• Enable any interrupts disabled by the subroutine. 

• Use an intersegment RET instruction since any 
subroutine call from BASIC is a FAR call. 

• Restore all segment registers and the stack pointer 
(SP). All other registers and flags can be altered. 



The CALL Statement 



Execution of a CALL statement causes the following 
to occur: 

• For each parameter in the variable list, the 

variable's location is pushed onto the stack. The 
location is specified as a 2-byte offset into 
BASIC'S data segment. You can return values to 
BASIC through the parameters by changing the 
values of the variables pointed to by the parameter 
list. 

The CALLed subroutine must know how many 
parameters were passed. Parameters are 
referenced by adding a positive offset to BP after 
the called subroutine moves the current stack 
pointer into BP. The first instruction in your 
subroutine should be: 

PUSH BP ;SAVE BP 

MOV BP, SP ;M0VE SP TO BP 
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The offset into the stack of any one parameter is 
calculated as follows: 

OFFSET from BP = 2 *(N - M) + 6 

where N is the total number of parameters passed 
and M is the position of the specific parameter in 
the parameter list on the CALL statement. M can 
range from 1 to N. 

In the Macro Assembler, the "STRUC" pseudo-op 
is a conventional way of defining the contents of 
the stack, showing the location of parameters. 



;Saved BASIC'S bp 

;0ffset to RET to BASIC 

;Seg to RET to BASIC 

;0ffset to Nth parameter 



FRAME 


STRUC 




SAVE BP 


DW 


? 


RET OFF 


DW 


? 


RET SEG 


DW 


? 


PARMN 


DW 


? 


PARM1 


DW 


? 


FRAME 


ENDS 





;0ffset to first parameter 



DADMCT7C mi| nCCCTT HADM1 .nrCCCT DTTCCC . 

(To be used as operand on RET) 

Warning: You must make sure that the 
parameters in the CALL statement match in 
number, type, and length the parameters expected 
by the subroutine; for instance, double-precision 
(8-byte) values. 

• Control is transferred to the assembly language 
subroutine using the segment specified in the first 
DEF SEG statement and the offset specified in the 
CALL statement. 

• The return segment ID specified in the CS register 
and the offset are pushed onto the stack. 

• When you call a subroutine using a CALL 
statement that specifies parameters, the subroutine 
must return with a RET N, where N is twice the 
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number of parameters in the list. This adjusts the 
stack to the condition at the start of the calling 
sequence. 

The CALL statement does not always have 
parameters. Also, if your routine is located in an 
integer array, it is possible to pass parameters in 
the array itself instead of through the CALL 
statement. 
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Memory Map 



This is a memory map for Disk and Advanced BASIC. DOS and the BASIC 
extensions are not present for Cassette BASIC. Addresses are in the 
hexadecimal form SEGMENT:OFFSET. 



0000:0000 



START OF 

USER AREA 

TOP OF CS — 



6 
4 
K 

M 

A 

X 

I 

M 

U 

M 



TOP OF 
DS,ES,SS 



A000:0000 



SYSTEM INTERRUPT VECTORS 



DOS 



DOS WORKAREA 



BASIC EXTENSIONS 



INTERPRETER WORKAREA 
File Buffers 
COM Buffers 
RS232 Code 



YOUR BASIC PROGRAM 



SCALARS 



ARRAYS 

FREE MEMORY [FRE(O)] 
STRING SPACE f 



BASIC STACK 



SPACE FOR USER-INSTALLED 
MEMORY EXPANSION 



Allocation of space in 
this area is 
determined by the IF., 
IS:, and /C: switch 
settings when BASIC 
is invoked. Presence 
of RS232 code adds 
approximately 1500 
bytes. Boundaries of 
buffers and RS232 
code are dynamic. 

These areas are 
allocated dynamically 
during program 
execution. Each area 
expands in the 
indicated direction. 

When string space 
and array space meet, 
there is no free 
memory. 

Stack size is 512 
bytes unless set by 
CLEAR command. 



F400:0000 



SYSTEM 



SCREEN BUFFER 



READ-ONLY MEMORY -BIOS 
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Appendix C. Communications 



This appendix describes the BASIC statements 
required to support RS232 asynchronous 
communication with other computers and peripherals. 



Opening a Communications File 

OPEN "COM... allocates a buffer for input and 
output in the same fashion as OPEN for disk files. See 
"OPEN "COM.... 



Communication I/O 



Since each communications adapter is opened as a file, 
all input/output statements that are valid for disk files 
are also valid for communications. 

Communications sequential input statements are the 
same as those for disk files. They are: 

INPUT # 
LINE INPUT # 
INPUTS 

Communications sequential output statements are also 
the same as those for disk files, and are: 

PRINT # 
PRINT # USING 
WRITE # 

See "INPUT" and "PRINT" for details of coding 
syntax and usage. 
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GET and PUT for Communications Files 

GET and PUT are only slightly different for 
communications files than for disk files. They are 
used for fixed length I/O from or to the 
communications file. Instead of specifying the record 
number to be read or written, you specify the number 
of bytes to be transferred into or out of the file buffer. 
This number cannot exceed the value set by the LEN 
option on the OPEN "COM... statement. See "GET" 
and "PUT." 



I/O Functions 

The most difficult aspect of asynchronous 
communication is processing characters as fast as they 
are received. At rates of 1200 bps or higher, it may 
be necessary to suspend character transmission from 
the other computer long enough to "catch up." This 
can be done by sending XOFF (CHR$(19)) to the 
other computer and XON (CHR$(17)) when you are 
ready to resume. XOFF tells the other computer to 
stop sending, and XON tells it to start sending again. 

Note: This is a commonly used convention, but it 
is not universal. Whether it is valid depends on the 
protocol implemented between you and the other 
computer or peripheral. 

Disk BASIC and Advanced BASIC provide three 
functions that help determine when an "overrun" 
condition is likely to occur. These are: 

LOC(f) 
LOF(f) 
EOF(f) 

Note: A Communication buffer overflow can occur 
if a read is attempted after the input buffer is full 
(that is, when LOF(f) returns 0). 
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INPUTS Function 

The INPUTS function is preferred over the INPUT # 
and LINE INPUT # statements when reading 
communications files, since all ASCII characters may 
be significant in communications. INPUT # is least 
desirable because input stops when a comma or 
carriage return is seen. LINE INPUT # stops when a 
carriage return is seen. 

INPUTS allows all characters read to be assigned to a 
string. INPUTS (n,f) returns n characters from the #/ 
file. The following statements are efficient for reading 
a communications file: 

10 WHILE NOT E0F(1) 

20 A$=INPUT$(L0C(1),#1) 



process data returned in A$) 



100 WEND 

When there are characters in the buffer, line 20 
assigns them to A$, and they are processed. If there 
are more than 255 characters in the buffer, only 255 
are returned at a time to prevent String overflow. Since 
EOF(l) is false, input continues until the input buffer 
is empty. This procedure is simple, concise, and fast. 

To process characters quickly, avoid examining every 
character as you receive it. If you are looking for 
special characters (such as control characters), you 
can use the INSTR function to find them in the input 
string. 



A Sample Program 



The following program allows the IBM Personal 
Computer to be used as a conventional "dumb" 
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terminal in a full duplex mode. This program assumes 
a 300 bps line and an input buffer of 256 bytes (the 
/C: option was not used in the BASIC command). 

10 REM dumb terminal example 

20 'set screen to monochrome text mode 

30 ' and set width to 40 

40 SCREEN 0,0: WIDTH 40 

50 'turn off key display; clear screen 

60 '' make sure all files are closed 

70 KEY OFF: CLS: CLOSE 

80 'define numeric variables as integer 

90 DEFINT A-Z 

100 'define true and false 

110 FALSE=0: TRUE=N0T FALSE 

120 'define the XON, XOFF characters 

130 X0FF$=CHR$(19): X0N$=CHR$( 17) 

140 'open communications to file number 1, 

150 ' 300 bps, EVEN parity, 7 data bits 

160 OPEN "COM1:300,E,7" AS #1 

170 'use screen as a file, just for fun 

180 OPEN "SCRN:" FOR OUTPUT AS #2 

190 'turn cursor on 

LOCATE ,,1 

PAUSE=FALSE: ON ERROR GOTO 9000 
490 ' 

500 'send keyboard input to com line 
510 B$=INKEY$: IF B$<>"" THEN PRINT #1,B$; 
520 'if corn buffer is empty, check key in 
530 IF E0F(1) THEN 510 
540 'if buffer more than 1/2 full, then 
550 'set PAUSE flag to say input suspended, 
560 'send XOFF to host to stop transmission 
570 IF L0C(1)>128 THEN PAUSE=TRUE 
575 PRINT #1,X0FF$ 
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580 'read contents of com buffer 

590 A$=INPUT$(L0C(1),#1) 

600 'remove linefeeds to avoid double spaces 

610 'when input displayed on screen 

620 LFP=0 

625 'look for linefeed 

630 LFP=INSTR(LFP+1,A$,CHR$(10)) 

r /I n Tr i r~r\~ rt Tumi ut r^ a. r n ,>• ir-r-. ■■ \ II n 

u-+)0 ir Lrr^ya i nciN ruu4>V M$ ,Lrr ,1 j - 

645 GOTO 630 

650 'display com input, and check for more 
660 PRINT #2,A$;: IF LOC(1)>0 THEN 570 
670 'if transmission suspended by XOFF, 
680 'resume by sending XON 
690 IF PAUSE THEN PAUSE=FALSE 
695 PRINT #1,X0N$; 
700 'check for keyboard input again 
710 GOTO 510 

8999 'if error, print its number and retry 
PRINT "ERROR N0.";ERR: RESUME 



Notes on the Program 



"Asynchronous" communication implies character 
I/O as opposed to line or block I/O. Therefore, 
all PRINTs (either to communications file or to 
screen) are ended with a semicolon. This stops the 
carriage return normally issued at the end of the 
list of values to be printed. 

Line 90, where all numeric variables are defined as 
integers, is coded because any program looking for 
speed optimization should use integer counters in 
loops where possible. 

Note in line 510 that INKEY$ will return a null 
string if no character is pending. 
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Operation of Control Signals 



The output from the Asynchronous Communications 
Adapter conforms to the Electronic Industries 
Association (EIA) RS232-C standard for interface 
between Data Terminal Equipment (DTE) and Data 
Communications Equipment (DCE). This standard 
defines several control signals that are transmitted or 
received by your IBM Personal Computer to control 
the interchange of data with another computer or 
peripheral. These signals are DC voltages that are 
either ON (greater than +3 volts) or OFF (less than 
-3 volts). See the IBM Personal Computer Technical 
Reference. 



Control of Output Signals with OPEN 

When you start BASIC on your IBM Personal 
Computer, the RTS (Request To Send) and DTR 
(Data Terminal Ready) lines are held off. When an 
OPEN "COM... statement is performed, both of these 
lines are normally turned on. However, you can 
specify the RS option in the OPEN "COM... 
statement to suppress the RTS signal. The lines 
remain on until the communications file is closed (by 
CLOSE, END, NEW, RESET, SYSTEM, or RUN 
without the R option). Even if the OPEN "COM... 
statement fails with an error (as described below), the 
DTR line (and RTS line, if applicable) is turned on 
and stays on. This allows you to retry the OPEN 
without having to execute a CLOSE. 



Use of Input Control Signals 

Normally, if either the CTS (Clear To Send) or DSR 
(Data Set Ready) lines are off, then an OPEN 
"COM... statement does not execute. After one 
second, BASIC returns a Device timeout error (error 
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code 24). The Carrier Detect (sometimes called 
Receive Line Signal Detect) can be either on or off; it 
has no effect on the operation of the program. 

However, you can specify how you want these lines 
tested with the RS, CS, DS, and CD options on the 
OPEN "COM... statement. See "OPEN" COM... 

Statement." 

If any of the signals being tested are turned off while 
the program is executing, I/O statements associated 
with the communications file do not work. For 
example, when you execute a PRINT # statement after 
the CTS or DSR line is turned off, a Device fault (code 
25) or Device timeout (code 24) error occurs. The 
RTS and DTR remain on even if such an error occurs. 

You can test for a line disconnect by using the INP 
function to read the bits in the MODEM Status 
Register on the Asynchronous Communications 
Adapter. See the following section, "Testing for 
Modem Control Signals" for details. 



Testing for Modem Control Signals 



Four input control signals are picked up by the 
Asynchronous Communications Adapter. These 
signals are CTS and DSR (described previously) 
Carrier Detect (sometimes called Received Line Signal 
Detect) (pin 8), and Ring Indicator (pin 22). You can 
specify how you want to test the CTS, DSR, and CD 
lines with the OPEN "COM... statement. Ring 
Indicator is not used at all by the communications 
function in BASIC. 

If you need to test for any of these signals in a 
program, you can check the bits corresponding to 
these signals in the MODEM Status Register on the 
Asynchronous Communications Adapter. To read the 
8 bits in this register, use the INP function; 
INP(&H3FE) to read the register on an unmodified 
communications adapter; and INP(&H2FE) to read it 
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on a modified communications adapter. See the 
"Asynchronous Communications Adapter" section of 
the IBM Personal Computer Technical Reference 
manual for a description of which bits in the Status 
Register correspond to which control signals. You can 
also use the Delta bits in this register to determine if 
transient signals have appeared on any of the control 
lines. Note that for a control signal to have meaning, 
the pin corresponding to that signal must be connected 
in the cable to your modem or to the other computer. 

You can also test for bits in the Line Status Register 
on the Asynchronous Communications Adapter. Use 
INP(&H3FD) to access this register on an unmodified 
communications adapter, and INP(&H2FD) to access 
it on a modified communications adapter. Again, the 
bits are described in the IBM Personal Computer 
Technical Reference. These bits can be used to 
determine what types of errors have occurred on 
receipt of characters from the communications line or 
whether a break signal has been detected. 



Direct Control of Output Control Signals 

You can control the RTS or DTR control signals 
directly from a BASIC program with an OUT 
statement. The on/off states of these signals are 
controlled by bits in the MODEM Control Register on 
the Asynchronous Communications Adapter. The 
address of this register is &H3FC on an unmodified 
communications adapter and &H2FC on a modified 
communications adapter. The IBM Personal 
Computer Technical Reference describes which of 
these bits correspond to which signals. 

You can also change bits in the Line Control Register 
on the Asynchronous Communications Adapter. Be 
careful in modifying these bits because most of them 
have been set by BASIC when an OPEN statement is 
executed and changing a bit can cause 
communications failure. The Line Control Register is 
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at address &H3FB on an unmodified communications 
adapter and at address &H2FB on a modified 
communications adapter. 

When changing bits in either the MODEM Control 
Register or the Line Control Register, first read the 
register (with an INP function), and then rewrite the 
register with only the pertinent bit or bits changed. 

A bit you may wish to control in the Line Control 
Register is bit 6, the Set Break bit. This bit permits 
you to produce a Break signal on the communications 
send line. A Break is often used to signal a remote 
computer to stop transmission. Typically a Break lasts 
for 1 /2 second. To produce such a signal, you must 
turn on the Set Break, wait for the desired time of the 
Break signal, and then turn the bit off. The following 
BASIC statements produce a Break signal of about 
1/2 second duration on an unmodified 
communications adapter. 

10 IC%=INP(&H3FB) 

20 'qet contents of modem reqister 

30 IZ%=IC% OR &H4040 'turn ON the Set Break bit 

50 OUT &H3FB,IZ% 

60 'transmit to modem control register 

70 FOR 1=1 TO 500: NEXT I 

80 'delay half a second 

90 OUT &H3FB,IC% 'turn Set Break bit OFF in registes 

100 'turn Set Break bit OFF in register 



Communication Errors 

Errors occur on communication files in the following 
order: 

1 . When opening the file— 

a. Device timeout if one of the signals to be tested 
(CTS, DSR, or CD) is missing. 

2. When reading data- 
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a. Com buffer overflow if overrun occurs. 

b. Device I/O error for overrun, break, parity, or 
framing errors. 

c. Device fault if you lose DSR or CD. 
3. When writing data — 

a. Device fault if you lose CTS, DSR, or CD on a 
Modem Status Interrupt while BASIC was 
doing something else. 

b. Device timeout if you lose CTS, DSR, or CD 

while waiting to put data in the output buffer. 
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Appendix D. ASCII Character Codes 



The following table lists all the ASCII codes (in 
decimal) and their associated characters. These 
characters can be displayed using PRINT CHR$(«), 
where n is the ASCII code. The column headed 
"Control Character" lists the standard interpretations 
of ASCII codes to 3 1 (usually used for control 
functions or communications). 

Each of these characters can be entered from the 

keyboard by pressing and holding the Alt key, then 

pressing the digits for the ASCII code on the numeric 

keypad. Note, however, that some of the codes have 
special meaning to the BASIC Program Editor. It uses 

its own interpretation for the codes and may not 

display the special character listed here. 
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ASCII 






Control 


ASCII 




Value 


Character 


Character 


Value 


Charac 


000 


(null) 




NUL 


032 


(space 


001 


© 




SOH 


033 


l 


002 


© 




STX 


034 


" 


003 


V 




ETX 


035 


# 


004 


♦ 




EOT 


036 


3> 


005 


♦ 




ENQ 


037 


% 


006 


4 




ACK 


038 


& 


007 


(beep) 




BEL 


039 


' 


008 


a 




BS 


040 


( 


009 


(tab) 




HT 


041 


) 


010 


(line feed) 


LF 


042 


* 


011 


(home) 




VT 


043 


+ 


012 


(form feed) 


FF 


044 


, 


013 


(carriage return) 


CR 


045 


- 


014 


J3 




SO 


046 




015 


# 




SI 


04 7 


/ 


016 


► 




DLE 


048 





017 


M 




DC1 


049 


1 


018 


♦ 




DC2 


050 


2 


019 


n 




DC3 


051 


3 


020 


<TT 




DC4 


052 


4 


021 


§ 




NAK 


053 


5 


022 


r 




SYN 


054 


6 


023 




ETB 


055 


7 


024 


4 




CAN 


056 


8 


025 


1 




EM 


057 


9 


026 


-+- 




SUB 


058 




027 


— 




ESC 


059 




028 


(cursor 


right) 


FS 


060 


< 


029 


(cursor 


left) 


GS 


061 


= 


030 


(cursor up) 


RS 


062 


> 


031 


(cursor 


down) 


US 


063 


? 
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ASCII 

Value Character 

064 @ 

065 A 

066 B 

067 C 

068 D 

069 E 

070 F 

071 G 

072 H 

073 I 

074 J 

075 K 

076 L 

077 M 

078 N 

079 O 

080 P 

081 Q 

082 R 

083 S 

084 T 

085 U 

086 V 

087 W 

088 X 

089 Y 

090 Z 

091 [ 

092 \ 

093 ] 

094 A 

095 - 



ASCII 




Value 


Character 


096 


' 


097 


a 


098 


b 


099 


c 


100 


d 


101 


e 


102 


f 


103 


g 


104 


h 


105 


i 


106 


J 


107 


k 


108 


I 


109 


m 


110 


n 


111 


o 


112 


P 


113 


q 


114 


r 


115 


s 


116 


t 


117 


u 


118 


V 


119 


w 


120 


X 


121 


y 


122 


z 


123 


{ 


124 


I 


125 


} 


126 


~ 


127 


a 
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ASCII 




Value 


Character 


128 


Q 


129 


u 


130 


e 


131 


a 


1 oo 


3 


133 


a 


134 


a 


135 


<? 


136 


e 


137 


e 


138 


e 


139 


i 


140 


i 


141 


i 


142 


A 


143 


A 


144 


E 


145 


ae 


146 


/£ 


147 





148 


o 


149 


6 


150 


U 


151 


u 


152 


V 


153 


6 


154 


u 


155 


<t 


156 


£ 


157 


X 


158 


Pt 


159 


/ 



ASCII 




Value 


Character 


160 


a 


161 


\ 


162 


6 


163 


u 


164 


n 


165 


N 


166 


a 


167 





168 


<: 


169 


r ~ 


170 


~\ 


171 


y 2 


172 


Va 


173 


i 


174 


(( 


175 


» 


176 




177 




178 




179 


I 


180 


H 


181 


=l 


182 


HI 


183 


~n 


1 84 


=i 


185 


={l 


186 


|| 


187 


=i1 


188 


=U 


189 


_y 


190 


=j 


191 


— i 
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ASCII 




Value 


Character 


192 


L 


193 


_l_ 


194 


~r 


195 


I- 


196 


— 


197 


+ 


198 


(= 


199 


Ih 


200 


it 


201 


fr 


202 


-)L 


203 


T? 


204 


lr 


205 


= 


206 


JL 


207 


=!= 


208 


_U_ 


209 


=r 


210 


~n~ 


211 


u_ 


212 


fc= 


213 


F 


214 


rr 


215 


+ 


216 


4= 


217 


_i 


218 


r 


219 


■ 


220 


™ 


221 


1 


222 


1 


223 


■ 



ASCII 

Value Character 

224 ex 

225 j3 

226 r 

227 7T 

228 I 

229 cr 

230 P 

231 t 

232 <5 

233 -e- 

234 n 

235 6 

236 oo 

237 

238 ( 

239 n 

240 = 

241 ± 

242 > 

243 < 

244 f 

245 J 

246 ^ 

247 as 
248 

249 
250 

251 V"" 

252 n 

253 2 

254 ■ 

255 (blank 'FF') 
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Extended Codes 



For certain keys or key combinations that cannot be 
represented in standard ASCII code, an extended code 
is returned by the INKEY$ system variable. A null 
character (ASCII code 000) will be returned as the 
first character of a two-character string. If a 
two-character string is received by INKEY$, go back 
and examine the second character to determine the 
actual key pressed. Usually, this second code is the 
scan code of the primary key that was pressed. The 
ASCII codes (in decimal) for this second character 
and the associated key(s) are listed on the next page. 
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Second 

Code Meaning 

3 (null character) NUL 

15 (shifttab) — <-■- + 

16-25 Alt- Q, W, E, R, T, Y, U, I, O, P 

30-38 Alt- A, S, D, F, G, H, J, K, L 

44-50 Alt- Z, X, C, V, B, N, M 

59-68 Function keys Fl through F10 (when 
disabled as soft keys) 

7 1 Home 

72 Cursor Up 

73 PgUp 

75 Cursor Left 

77 Cursor Right 

79 End 

80 Cursor Down 

81 PgDn 

82 Ins 

83 Del 

84-93 Fl 1-F20 (Shift- Fl through F10) 

94-103 F21-F30 (Ctrl- Fl through F10) 

1 04- 1 1 3 F3 1 -F40 (Alt- F 1 through F 1 0) 

114 Ctrl-Prtsc 

1 1 5 Ctrl-Cursor Left (Previous Word) 

1 1 6 Ctrl-Cursor Right (Next Word) 

117 Ctrl-End 

118 Ctrl-PgDn 

119 Ctrl-Home 

120-131 Alt- 1,2,3,4,5,6,7,8,9,0,-,= 

132 Ctrl-Pg Up 
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Appendix E. Scan Codes 



Key 


Scan code 
in hex 


Key 


Scan code 
in hex 


ESC 


01 


i^j- 


OF 


! 1 


02 


Q 


10 


@2 


03 


W 


11 


#3 


04 


E 


12 


$4 


05 


R 


13 


% 5 


06 


T 


14 


a 6 


07 


Y 


15 


&7 


08 


U 


16 


* 8 


09 


I 


17 


(9 


0A 


o 


18 


)0 


OB 


p 


19 


— 


OC 


{[ 


1A 


+ = 


OD 


}] 


IB 


«- 


OE 


«-J 


1C 



E-l 



Key 


Scan code 
in hex 


Key 


Scan code 
in hex 


Ctrl 


ID 


: \ 


2B 


A 


IE 


z 


2C 


S 


IF 


X 


2D 


D 


20 


c 


2E 


F 


21 


V 


2F 


G 


22 


B 


30 


H 


23 


N 


31 


J 


24 


M 


32 


K 


25 


< , 


33 


L 


26 


> 


34 


• 5 


27 


?/ 


35 


a > 


28 


ORight 


36 


r*j ' 


29 


PrtSc * 


37 


OLeft 


2A 


Alt 


38 



E-2 



Key 


Scan code 
in hex 


Key 


Scan code 
in hex 


Sp bar 


39 


7 Home 


47 


Caps 
Lock 


3A 


8t 


48 


Fl 


3B 


9 PgUp 


49 


F2 


3C 


— 


4A 


F3 


3D 


4<r- 


4B 


F4 


3E 


5 


4C 


F5 


3F 


6-* 


4D 


F6 


40 


+ 


4E 


F7 


41 


1 End 


4F 


F8 


42 


2\ 


50 


F9 


43 


3 PgDn 


51 


F10 


44 


1ns 


52 


Num 
Lock 


45 


Del 


53 


Scroll 
Lock 


46 
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Glossary 



absolute coordinates In computer graphics, a pair of 
values that specify the location of a point with respect 
to the origin of the coordinate system. Contrast with 
relative coordinates. 

access mode A technique used to get a specific logical 
record from, or put a logical record into, a file. 

accuracy The quality of being free from error. On a 
machine, this is actually measured and refers to the 
size of the error between the actual number and its 
value as stored in the machine. 

active page On the Color/Graphics Monitor Adapter, 
the part of the screen buffer that has information 
written to it. It can be different from the part of the 
screen buffer whose information is being displayed. 

adapter A mechanism for attaching parts. 

address (noun) The location of a register, a particular 
part of memory, or some other data source or 
destination, (verb) To refer to a device or a data item 
by its address. 

addressable point In computer graphics, any point in a 
display space that can be addressed. Such points are 
finite in number and form a discrete grid over the 
display space. 

algorithm A set of well-defined rules for the solution 
of a problem in a finite number of steps. 

allocate To assign a resource, such as a disk file or a 
part of memory, to a specific task. 

alphabetic character A letter of the alphabet. 
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alphameric or alphanumeric Pertaining to a character 
set that contains letters and digits. 

application program A computer program that 
accomplishes a specific task, such as word processing 
or processing payroll data. 

argument A value that is passed from a calling 
program to a function. 

arithmetic overflow Same as overflow. 

array An arrangement of elements in a table format. 



ASCII American National Standard Code for 
Information Interchange. The standard code used for 
exchanging information among data processing 
systems and associated equipment. The ASCII set 
consists of control characters and graphic characters. 



asynchronous Without regular time relationship; 
unpredictable with respect to the execution of a 
program's instructions. 

attribute A property or characteristic of one or more 
items. 



background The area that surrounds the subject. In 
particular, the part of the display screen surrounding a 
character. 

backup A system, device, file, or facility that can be 
used as an alternative in case of a malfunction or loss 
of data. 

baud A unit of signaling speed equal to the number of 
discrete conditions or signal events per second. 
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binary Pertaining to a condition that has two possible 
values or states. Also, refers to the Base 2 numbering 
system. 

bit A binary digit. 

blank A part of a data medium in which no characters 
are recorded. Also, the space character. 

blinking An intentional regular change in the intensity 
of a character on the screen. 

boolean value A numeric value that is interpreted as 
"true" (if it is not zero) or "false" (if it is zero). 

bootstrap An existing version, perhaps a primitive 
version, of a computer program that is used to 
establish another version of the program. Can be 
thought of as a program that loads itself. 

bps Bits per second. 

bubble sort A technique for sorting a list of items into 
sequence. Pairs of items are examined, and exchanged 
if they are out of sequence. This process is repeated 
until the list is sorted. 

buffer An area of storage that is used to compensate 
for a difference in rate of flow of data, or time of 
occurrence of events, when transferring data from one 
device to another. Usually refers to an area reserved 
for I/O operations, into which data is read or from 
which data is written. 

bug An error in a program. 

byte The representation of a character in binary. 
Eight bits. 



call To bring a computer program, a routine, or a 
subroutine into effect, usually by specifying the entry 
conditions and jumping to an entry point. 
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carriage return character (CR) A character that causes 
the print or display position to move to the first 
position on the same line. 

channel A path along which signals can be sent; for 
example, a data channel or an output channel. 

character A letter, digit, or other symbol that is used 
as part of the organization, control, or representation 
of data. A connected sequence of characters is called 
a character string. 

character device A device that is designed to do 
character I/O in a serial manner, like CON, AUX, and 
PRN. 

clipping See line clipping. 

clock A device that generates periodic signals used for 
synchronization. Each signal is called a clock pulse or 
clock tick. 

code (verb) To represent data or a computer program 
in a symbolic form that can be accepted by a 
computer; to write a routine, (noun) Loosely, one or 
more computer programs, or part of a program. 

comment An explanatory statement in a program. 
Comments include information that can be helpful in 
running the program or reviewing the output listing. 

communication The transmission and reception of 
data. 

complement An "opposite" number. In particular, a 
number that can be derived from a given number by 
subtracting it from another given number. 

compression The moving of fragmented data into a 
contiguous region of memory, leaving other regions 
free for other data. 
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concatenation The operation that joins two strings 
together in the order specified, forming a single string 
with a length equal to the sum of the lengths of the 
two strings. 

constant A fixed value or data item. 

control character A character whose occurrence in a 
particular context starts, modifies, or stops a control 
operation. A control operation is an action that 
affects the recording, processing, transmission, or 
interpretation of data; for example, carriage return, 
font change, or end of transmission. 

control data See control character. 

coordinates Numbers that identify a location on the 
display. 

current directory The default directory for each drive 
on a computer system. This is the directory that 
BASIC searches if you enter a filename without a path 
specification. 

cursor A movable marker on the display screen that 
indicates where the next character will be entered, 
replaced, or deleted. 



debug To find and eliminate mistakes in a program. 

default A value or option that is assumed when none 
is specified. 

delimiter A character that groups or separates words 
or values in a line of input, such as commas, colons, 
semicolons, and blanks. 

device driver A program that interfaces input/output 
to a device. 

diagnostic Pertaining to the detection and isolation of 
a malfunction or mistake. 
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directory A table of identifiers and references to the 
corresponding items of data. For example, the 
directory for a disk contains the names of files on the 
disk (identifiers), along with information that tells 
DOS where to find the file on the disk. See also 
tree -structured directories. 

disabled A state that prevents the occurrence of 
certain types of interruptions. 



DOS Disk Operating System. In this book, refers only 
to the IBM Personal Computer Disk Operating 
System. 



double precision In the representation of numbers, the 
degree of accuracy that requires the use of two 
computer words. In double precision, numbers are 
stored with 17 digits of accuracy and printed with up 
to 16 digits. Contrast with single precision. 

dummy Having the appearance of a specified thing but 
not having the capacity to function as such. For 
example, a dummy argument to a function. 

duplex In data communication, pertaining to a 
simultaneous two-way independent transmission in 
both directions. Same as "full duplex." 

dynamic Occurring at the time of execution. 



echo To reflect received data to the sender. For 
example, keys pressed on the keyboard are usually 
echoed as characters displayed on the screen. 

edit To enter, modify, or delete data. 

element A member of a set; in particular, an item in 
an array. 
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enabled A state of the processing unit that allows 
certain types of interruptions. 

end of file (EOF) A "marker" immediately following 
the last record of a file, signaling the end of that file. 

environment A set of text strings, less than 32K bytes 
total, that conveys various configuration parameters. 

event An occurrence or happening. In IBM Personal 
Computer Advanced BASIC, refers to the events 
tested by ON COM(n), ON KEY(n), ON PEN, ON 
PLAY(n), ON STRIG(n), and ON TIMER. 

execute To perform a computer instruction or 
program. 

expression A notation that has a value. Usually, a 
combination of variables, constants, and operators, 
such as X - 3. 



fault An accidental condition that causes a device to 
fail to perform in a required manner. 

field In a record, a specific area used for a particular 
category of data. 

file A set of related records treated as a unit. 

fixed disk The IBM nonremovable disk drive that has 
no drive cover or handle. 

flag Any of various types of indicators used for 
identification; for example, a character that signals the 
occurrence of some condition. 

font A family or assortment of characters of a 
particular size and style. 

foreground The part of the display area that is the 
character itself. 
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format The particular arrangement or layout of data 
on a data medium, such as the screen or a disk. 

form feed (FF) A character that causes the print or 
display position to move to the next page. 

function A procedure that returns a value that 
depends on the value of one or more independent 
variables in a specified way. 

function keys Keys on the computer keyboard that tell 
the system to perform certain commands. The keys 
F1-F10 on the keyboard. 



graphic A symbol produced by a process such as 
handwriting, printing, or drawing. 



half duplex In data communication, pertaining to an 
alternate, one way at a time, independent 
transmission. 

hard copy A printed copy of machine output in a 
visually readable form. 

hertz (Hz) A unit of frequency equal to one cycle per 
second. 

hierarchy A structure having several levels, arranged 
in a tree-like form. "Hierarchy of operations" refers 
to the relative priority assigned to arithmetic or logical 
operations that must be performed. 

host The primary or controlling computer in a 
multiple computer installation. 

housecleaning An operation in which BASIC 
compresses string space by collecting all its useful data 
and frees up unused areas of memory that were once 
used for strings. 



Glossary-8 



implicit declaration The establishment of a dimension 
for an array without it having been explicitly declared 
in a DIM statement. 

increment A value used to alter a counter. 

initialize To set counters, switches, addresses, or 
contents of memory to zero or other starting values at 
the beginning of, or at prescribed points in, the 
operation of a computer routine. 

instruction In a programming language, any 
meaningful expression that specifies one operation and 
its operands, if any. 

integer One of the numbers 0, ±1, ±2, ±3, ... 

integrity Preservation of data for its intended purpose; 
data integrity exists as long as accidental or malicious 
destruction, alteration, or loss of data are prevented. 

interface (noun) A shared boundary in which two 
systems interact. 

interpreter A system program that is used to translate 
and execute each source language statement of a 
computer program before going on to the next 
statement. 

interrupt To stop a process in such a way that it can 
be resumed. 

intra-application communication area A 16-byte area in 
low memory starting at address H4F0 which is 
reserved for use by any application. 

invoke To activate a procedure at one of its entry 
points. 



joystick A computer graphics lever that can pivot in 
all directions and is used as a locator device. 



Glossary- 9 



justify To align characters horizontally or vertically to 
fit the positioning constraints of a required format. 



K When referring to memory capacity, two to the 
tenth power (1024 in decimal notation). 



keyword One of the predefined words of a 
programming language; a reserved word. 



leading The first part of something; for example, 
leading zeros or leading blanks in a character string. 

light pen A light-sensitive device that can be used 
instead of the keyboard to select a location on the 
screen. 

line When referring to text on a screen or printer, one 
or more characters output before a return to the first 
print or display position. When referring to input, a 
string of characters accepted by the system as a single 
block of input; for example, all characters entered 
before you press the Enter key. In graphics, a series 
of points drawn on the screen to form a straight line. 
In data communications, any physical medium, such as 
a wire or microwave beam, that is used to transmit 
data. 

line clipping A process in which points referenced 
outside a coordinate range become invisible in the 
viewing area. Any image crossing the viewing area 
(lying partially within and partially without) is cut off 
or "clipped" at the viewing area boundaries so that 
only points in range appear. 

line feed (LF) A character that causes the print or 
display position to move to the corresponding position 
on the next line. 

literal An explicit representation of a value, especially 
a string value; a constant. 
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location Any place in which data can be stored. 

logical line A string of text between one Enter and 
another. It is treated by BASIC as a single unit. 

loop A set of instructions that can be executed 
repeatedly while a certain condition is true. 



M Mega; one million. When referring to memory, 
two to the twentieth power; 1,048,576 in decimal 
notation. 



machine infinity The largest number that can be 
represented in a computer's internal format. 

mantissa For a number expressed in floating point 
notation, the numeral that is not the exponent. 

mapping The translation of coordinate values between 
the world coordinate system, as defined by the 
WINDOW statement, and the physical coordinate 
system of the viewport. 

mask A pattern of characters that controls the 
retention or elimination of another pattern of 
characters. 

matrix An array with two or more dimensions. 

matrix printer A printer in which each character is 
represented by a pattern of dots. 

megabyte 1,048,576 bytes. Same as two to the 
twentieth power. 

menu A list of available operations. You select from 
the list the operation you want. 
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nest To incorporate a structure into another structure 
of the same kind. For example, you can nest loops 
within other loops or call subroutines from other 
subroutines. 

notation A set of symbols, and the rules for their use, 
for the representation of data. 

null Empty, having no meaning. In particular, a string 
with no characters in it. 



octal Pertaining to a Base 8 number system. 

offset The number of units from a starting point (in a 
record, control block, or memory) to some other 
point. For example, in BASIC the actual address of a 
memory location is given as an offset in bytes from the 
location defined by the DEF SEG statement. 

on-condition An occurrence that could cause a 
program interruption. It can be the detection of an 
unexpected error, or of an occurrence that is expected, 
but at an unpredictable time. 

operand An expression in an instruction that must be 
acted upon when the instruction is carried out. 

operating system Software that controls the execution 
of programs; often used to refer to DOS. 

operation A program step undertaken or executed by 
a computer. 

operator A symbol that represents the action to be 
performed in a mathematical operation. 

overflow The result of an operation that exceeds the 
capacity of the intended unit of storage. 

overlay To use the same areas of memory for different 
parts of a computer program at different times. 
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overwrite To record into an area of storage so as to 
destroy the data that was previously stored there. 



pad To fill a block with dummy data, usually zeros or 
blanks. 

page Part of the screen buffer that can be displayed 
and/or written on independently. 

palette In computer graphics, a range of colors. 

parameter A variable that is given a constant value for 
a specified application. Or, a name in a procedure that 
refers to an argument passed to that procedure. 

parity check A technique for testing transmitted data. 
Typically, a binary digit is appended to a group of 
binary digits to make the sum of all the digits either 
always even (even parity) or always odd (odd parity). 

path A specified direction used to find a particular 
file. Used with directories and any command or 
statement that accepts a file specification. 

peripheral device In a computer system, any 
equipment that provides the processing unit with 
outside communication. 

physical coordinate system The logical limits of the 
screen. See "View" and "Window" statements in this 
manual. 

pixel A point or location on a display screen that is 
used to form part of an image on the screen. Also, the 
bits that contain the information for that point. 

port An access point for data entry or exit. 

position In a string, each location that can be occupied 
by a character and that can be identified by a number. 
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precision A measure of the ability to distinguish 
between nearly equal values. 

prompt A message or symbol that appears on the 
screen, asking for information from the user. 

protect To restrict access to or use of all, or part of, a 
data processing system. 



queue A line or list of items waiting for service; the 
first item that goes into the queue is the first item to 
be serviced. 



random access memory Storage in which you can read 
and write to any desired location. Sometimes called 
"direct access storage." 

range The set of values that a quantity or function can 
take. 

raster scan A technique of generating a display image 
by a line-by-line sweep across the entire display 
screen. This is the way pictures are created on a 
television screen. 

read-only A type of access that allows data to be read 
but not modified. 

record A collection of related information treated as a 
unit. For example, in stock control, each invoice 
might be one record. 

register A storage device with a specified capacity 
such as a bit, a byte, or a computer word. 

relative coordinates In computer graphics, a pair of 
values that identify the location of a point by 
specifying displacements from some other point. 

reserved word A word that is defined in BASIC for a 

special purpose and cannot be used as a variable name. 
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resolution In computer graphics, a measure of the 
sharpness of an image, expressed as the number of 
lines per unit length. 

reverse image Highlighting a character field or cursor 
by reversing its color and its background. 

root directory The directory that is created on each 
disk when it is formatted. Also called the "base" or 
"main" directory. 

routine Part of a program, or a sequence of 
instructions called by a program, that can have some 
general or frequent use. 

row A horizontal arrangement of characters or other 
expressions. 



scalar A value or variable that is not an array. 

scale To change the representation of a quantity, 
expressing it in other units, so that its range is brought 
within a specified range. 

scaling In computer graphics, the process of 
WINDOW mapping world coordinates to physical 
coordinates. See "WINDOW Statement" in this 
manual. 

scan To examine sequentially, part by part. See raster 
scan. 

scroll To move all or part of the screen material up or 
down, left or right, to allow new information to 
appear. 

segment A particular 64K-byte area of memory. 

sequential access An access mode in which records are 
retrieved in the same order in which they were written. 
Each successive access to the file refers to the next 
record in the file, 
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single precision In the representation of numbers, the 
degree of accuracy that requires the use of one 
computer word. In single precision, seven digits are 
stored and up to seven digits are printed. Contrast 
with double precision. 

stack A method of temporarily storing data so that the 
last item stored is the first item to be processed. 

statement A meaningful expression that describes or 
specifies operations and is complete in the context of 
the BASIC programming language. 

stop bit A signal following a character or block that 
prepares the receiving device to receive the next 
character or block. 

storage A device, or part of a device, that can retain 
data. Memory. 

string A sequence of characters. 

subdirectory Any directory contained in the root 
directory list or within another subdirectory list. 

subscript A number that identifies the position of an 
element in an array. 

syntax The rules governing the structure of a 
language. 

syntax error An incorrect instruction resulting from a 
misspelling, missing or faulty punctuation, a missing or 
incorrect character. 



table An arrangement of data in rows and columns. 

target In an assignment statement, the variable whose 
value is being set. 

telecommunication Synonym for data communication. 
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terminal A device, usually equipped with a keyboard 
and display, capable of sending and receiving 
information. 

toggle Pertaining to any device having two stable 
states; to switch back and forth between the two 
states. 

trailing Located at the end of a string or number. For 
example, the number 1000 has three trailing zeros. 

trap A set of conditions describing an event to be 
intercepted and the action to be taken after the 
interception. 

tree-structured directory A group of related files and 
directories on the same disk organized in a hierarchical 
structure, as in a "family tree." 

truncate To remove the ending elements from a string. 

twos complement A form for representing negative 
numbers in the binary number system. 

typematic key A key that repeats as long as you hold it 
down. 



variable A quantity that can assume any of a given set 
of values. 

vector In computer graphics, a directed line segment. 
More generally, an ordered set of numbers, and so, a 
one-dimensional array. 

viewport In computer graphics, a defined area of the 
screen. 



window In computer graphics, a defined area in the 
world coordinate system. 
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world coordinate system A coordinate system not 
bounded by any limits - unlimited "space" in graphics. 

wraparound The process whereby parts of an object 
that are not visible within the window produce 
incorrectly drawn images due to the overflow of 
internal coordinates. 

write To record data in a storage device or on a data 
medium. 



zooming In computer graphics, causing an object to 
appear smaller or larger by moving the WINDOW and 
specifying various WINDOW sizes. 
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Index 



Special Characters 



?Redo from start 131 

# 268 



assignment statement 154 

ATN 6 

ATN Function 6 

AUTO 8 

AUTO Command 8 

automatic line numbers 8 



B 



ABS 4 

ABS Function 4 

absolute value 4 

active page 313 

Advanced feature A-3 

ampersand symbol 268 

animation 282 

append 220 

arctangent 6 

argument 346 

arrays 70,89,233 

ASC 5 

ASC Function 5 

ASCII code 310 

ASCII codes 5, 25, Appendix 

D 
converting to 5 
ASCII format 308 
aspect ratio 30, 76 
assembly language 

subroutines 17 
assembly language 

subroutines. Appendix B 



background 38, 237 
Bad file mode A-3 
Bad file name A-4 
Bad file number A-4 
Bad record number A-4 
BASIC Program Editor 263 
question mark for 
PRINT 263 
BASIC'S data segment 62 
BEEP 10 

BEEP Statement 10 
blinking characters 39 
BLOAD 11 
BLO AD Command 11 
border screen 38 
boundary 237, 358 
branching 120, 203 
BSAVE 15 
BSAVE Command 15 
burst, screen 312 



Index- 1 



CALL 17 

CALL Statement 17 
Can't continue A-4 
Can't continue after 

SHELL A-5 
cassette motor 193 
CAS1 168 
CAS1: 308 
CDBL 19 
CDBL Function 19 
CHAIN 20,47 
CHAIN Statement 20 
change current directory 23 
changes v 

character set Appendix D 
CHDIR 23 
CHDIR Command 23 
child process 317 
CHR$ 25,D-1 
CHR$ Function 25 
CINT 27 

CINT Function 27 
CIRCLE 28 
CIRCLE Statement 28 
CLEAR 32 
CLEAR Command 32 
clear screen 36 
clear system buffer 295 
clearing memory 196 
clock 323 
CLOSE 34 
close disk files 295 
CLOSE Statement 34,295 
CLS 36 

CLS Statement 36 
color 277, 357 
COLOR Statement 38,236, 

311 
COM 46 
COM(n) Statement 46 



comma in formatting 

string 270 
comments 291 
COMMON 20,47 
COMMON Statement 47 
Communication buffer 

overflow A-5 
communications 226, 

Appendix C 
communications buffer 227 
communications trapping 46, 

198 
compressed binary format 309 
computed 

GOSUB/GOTO 203 
CONT 48 

CONT Command 48 
converting degrees to 

radians 50 
converting from numbers for 

random files 191 
converting from numeric to 

octal 197 
converting numbers 19 
converting numbers from 

random files 53 
converting radians to degrees 6 
converting string to 

numeric 352 
converting to integer 27 
coordinates 
physical 370 
world 370 
coordinates, absolute or 

relative form 236, 277 
COS 50 

COS Function 50 
cosine 50 

create a directory 189 
creating tree structure 189 
CSNG 51 
CSNG Function 51 
CSRLIN 52 
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CSRLIN Variable 52 
cursor position 52, 172,262 
CVI, CVS, CVD 53 
CVI, CVS, CVD Functions 53 



D 



DATA 55,289 
data segment 62, 66 
DATA Statement 55 
DATES 57 
DATES Variable and 

Statement 57 
decisions 123 
declaring arrays 70 
declaring variable types 64 
DEFFN 59 
DEF FN Statement 59 
DEFSEG 62 
DEF SEG Statement 62 
DEFUSR 66 
DEF USR Statement 66 
DEFtype Statements 64 
DELETE Command 68 
deleting a file 150 
deleting a program 196 
deleting arrays 89 
deleting program lines 68 
Device fault A-6 
Device I/O error A-6 
Device timeout 180, A-6 
Device unavailable A-6 
DIM Statement 70 
dimensioning arrays 70 
DIR 102 
direct mode 201 
Direct statement in file A-7 
directory 23 
Disk full A-7 
disk I/O 309 



Disk media error A-7 
Disk not ready A-8 
Disk write protect A-8 
display pages 313 
display program lines 163 
Division by zero A-8 
documentation, internal 

program 291 
double asterisk 269 
double asterisk, dollar sign 270 
double dollar sign 270 
double precision 19 
DRAW Statement 72 
DS (BASIC'S Data 

Segment) 62 
Duplicate definition A-8 
duration, time 323 



E 



EDIT 79 

EDIT Command 79 

elapsed time 344 

ELSE 123 

encoded binary format 309 

END 80 

end of file 87 

END Statement 80 

ending BASIC 339 

ENVIRON 81 

ENVIRON Statement 81 

ENVIRONS 84 

ENVIRONS Function 84 

environment 81, 84 

EOF 87 

EOF Function 87 

ERASE 89 

ERASE (DOS) 150 

ERASE Statement 89 

erasing a file 150 
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erasing a program 1 96 
erasing arrays 89 
erasing program lines 68 
erasing variables 32 
ERDEV 91 
ERDEV and ERDEV$ 

Variables 91 
ERL 94 
ERR 94 

ERR and ERL Variables 94 
ERROR 96 

error codes 94, 96, Appendix 
A 
error line 94 

error messages Appendix A 
ERROR Statement 96 
error trapping 94, 96, 201, 297 
event trapping 148 

KEY(n) 148,205 

ONPLAY(n) 211 

ON TIMER 217 

PEN 209, 247 

STRIG(n) (joystick 
button) 214 
exchanging variables 338 
exclamation point symbol 267 
executing a program 306 
exit BASIC 339 
EXP 98 

EXP Function 98 
exponential function 98 
extended ASCII codes D-6 



false or true 310 
FIELD 99 
Field overflow A-9 
FIELD Statement 99 
File already exists A-9 



File already open A-9 

File not found A- 10 

file size 175 

file, position of 170 

FILES Command 102 

FILES 102 

FIX 105 

FIX Function 105 

fixed-length strings 1 82 

floor function 138 

FOR 106 

FOR and NEXT 

Statements 106 
FOR without NEXT A- 10 
foreground 38 
format, compressed or encoded 

binary 309 
formatting 267 
FRE 111 

FRE Function 111 
free space 32, 111 
frequency 323 
frequency table 324 
functions 3 



garbage collection 111 
GET (files) 113 
GET (graphics) 115 
GET Statement (Files) 113 
GET Statement 

(Graphics) 115 
glissando 325 
GOSUB 118,203 
GOSUB and RETURN 

Statements 118 
GOTO 120,203 
GOTO Statement 120 
GRAFT ABL Command 314 
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graphics statements 72,156 
CIRCLE 28 
COLOR 43 
DRAW 72 
GET 115 
LINE 156 
PAINT 236 
POINT function 258 
PSET and PRESET 277 
PUT 281 
VIEW 357 
WINDOW 370 



H 



HEX$ 122 
HEX$ Function 122 
hexadecimal 122 
high-intensity characters 39 
housecleaning 111 



INPUT 130 

INPUT # 133 

INPUT # Statement 133 

input file mode 220 

Input past end A-l 1 

INPUT Statement 130 

INPUTS 135, C-3 

INPUTS Function 135 

INSTR 137 

INSTR Function 137 

INT 138 

INT Function 138 

integer 

Internal error A-l 1 

invisible characters 41 

IOCTL 139 

IOCTL Statement 139 

IOCTL$ 141 

IOCTL$ Function 141 



I 



joystick 329 

joystick button 214, 334, 336 

jumping 120, 203 



I/O control 139 

IF 123 

IF Statement 123 

Illegal direct A- 10 

Illegal function call A- 10 

Incorrect DOS version A- 1 1 

increment 8, 293 

indent 340 

index (position in string) 137 

INKEY$ 127, D-6 

INKEY$ Variable 127 

INP 129 

INP Function 1 29 



K 



KEY 142 

KEY Statement 142 

KEY(n) 148 

KEY(n) Statement 148 

KILL 150 

KILL Command 150 
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LEFTS 152 
LEFTS Function 152 
left- justify 182 
LEN 153 
LEN Function 153 
length of file 175 
length of string 111, 153 
LET 154 

LET Statement 154 
light pen 209,247 
LINE 156 

Line buff er overflow A- 12 
line drawing in graphics 156 
linefeed 222 
LINE INPUT 160 
LINE INPUT # 161 
LINE INPUT # Statement 161 
LINE INPUT Statement 160 
LINE Statement 156 
LIST 163 

LIST Command 163 
list program lines 166 
listing files 102 
on disk 102 
listing files on cassette 168 
LLIST 166 
LLIST Command 166 
LOAD 167 
LOAD Command 167 
loading binary data 1 1 
LOC 170 
LOC Function 170 
LOCATE 172 
LOCATE Statement 172 
LOF 175 
LOF Function 175 
LOG 177 
LOG Function 177 
logarithm 177 



loops 106, 364 

LPOS 178 

LPOS Function 178 

LPRINT 179 

LPRINT and LPRINT USING 

Statements 179 
LPRINT Statement 265 
LPRINT USING 179 
LPT1: 166, 178, 179 
LSET 182 
LSET and RSET 

Statements 182 



M 



machine input port status 362 
machine language 

subroutines 17 
memory image 1 5 
memory map B-29 
MERGE 20, 184 
MERGE Command 184 
messages Appendix A 
MID$ 186 
MID$ Function and 

Statement 186 
minus sign 269 
Missing operand A- 12 
MKDIR 189 
MKDIR Command 189 
MKI$, MKS$, MKD$ 191 
MKI$, MKS$, MKD$ 

Functions 191 
mode, screen 312 
MOTOR 193 
MOTOR Statement 193 
music 250, 324 
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N 



NAME 194 

NAME Command 194 

NEW 196 

NEW Command 196 

newnum 293 

NEXT 106 

NEXT without FOR A- 12 

No RESUME A- 12 

notes, sound 324 

number of notes in buffer 255 



o 



OPEN 220 
OPEN "COM. . . 

Statement 226 
OPEN "COM. . . 226, C-6 
OPEN Statement 220 
opening files 220 
opening paths 220 
OPTION BASE 233 
OPTION BASE 

Statement 233 
OUT 234 
Out of data A- 12 
Out of memory A- 13 
Out of paper A- 13 
Out of string space A- 13 
OUT Statement 234 
output file mode 220 
Overflow A- 13 
overlay 20 



OCT$ 197 




OCT$ Function 197 




octal 197 


P 


offset 62, 66 


oldnum 293 




ONCOM(n) 198 




ON COM(n) Statement 198 


page, active 313 


ON ERROR 201 


page, visual 313 


ON ERROR Statement 201 


PAINT 236 


ONKEY(n) 205 


PAINT Statement 236 


ON KEY(n) Statement 205 


paint tiling 243 


ON PEN 209 


palette 43 


ON PEN Statement 209 


panning 373 


ONPLAY(n) 211 


Path not found A- 14 


ON PLAY(n) Statement 211 


Path/file access error A- 14 


ONSTRIG(n) 214 


paths 23 


ON STRIG(n) Statement 214 


paths, opening 220 


ON TIMER Statement 217 


patterns 243 


ONTIMER(n) 217 


PEEK 246 


ON-GOSUB 203 


PEEK Function 246 


ON-GOSUB and ON-GOTO 


PEN 247 


Statements 203 


PEN OFF Statement 248 


ON-GOTO 203 


PEN ON Statement 248 
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PEN Statement and 

Function 247 
physical coordinates 370 
PLAY 250 
PLAY Statement 250 
PLAY(n) 255 
PLAY(n) Function 255 
plus sign 269 
PMAP 256 
PMAP Function 256 
POINT 258 
POINT Function 258 
POKE 261 

POKE Statement 246, 261 
POS 262 

POS Function 262 
position in string 137 
position of file 170 
positioning the cursor 172 
precision 64 
PRESET 277 
PRINT 263 
PRINT # 273 
PRINT # and PRINT # USING 

Statements 273 
PRINT # USING 273 
print formatting 267 
PRINT Statement 263 
PRINT USING 267 
PRINT USING Statement 267 
print zones 263 
printing 179 
program stop 331 
protected files 308 
protection option 309 
PSET 277 
PSET and PRESET 

Statements 277 
punctuation, PRINT 

Statement 263 
PUT (files) 279 
PUT (graphics) 281 
PUT Statement (Files) 279 



PUT Statement 
(Graphics) 281 



R 



random files 99, 113,220 

random numbers 286, 303 

RANDOMIZE 286 

RANDOMIZE Statement 286 

READ 55,289 

READ Statement 289 

reel setting 220 

Redo 131 

related publications iv 

REM 291 

REM Statement 291 

remarks 291 

removing a directory 301 

RENAME 194 

Rename across disks A- 14 

renaming files 194 

RENUM 21,94,293 

RENUM Command 293 

renumber program lines 293 

repeating a string 337 

RESET 295 

RESET Command 295 

RESTORE 296 

RESTORE Statement 290, 

296 
RESUME 297 
resume execution 48 
RESUME Statement 297 
RESUME without error A- 15 
RETURN 118,299 
RETURN Statement 299 
RETURN without 

GOSUB A- 15 
reverse image characters 40 
RIGHTS 300 



Index- 8 



RIGHTS Function 300 

right- justify 182 

RMDIR 301 

RMDIR Command 301 

RND 303 

RND Function 303 

rounding to an integer 27 

RSET 182 

RUN 306 

RUN Command 306 



SAVE 308 

SAVE Command 308 
saving binary data 15 
scan codes Appendix E, E-l 
SCREEN Function 310 
screen shifting 234 
SCREEN Statement 312 
seeding random number 
generator 286 
segment of storage 62 
sequential files 220 
SGN 316 
SGN Function 316 
SHELL 317 
SHELL Statement 317 
shifting screen image 234 
sign of a number 316 
SIN 322 

SIN Function 322 
sine 322 

single precision 5 1 
soft keys 142 
SOUND 323 
SOUND Statement 323 
sounds 10, 250, 323 
space 370 



SPACES 326 

SPACES Function 326 

spaces 264 

SPC 327 

SPC Function 327 

SQR 328 

SQR Function 328 

square root 328 

stack space 32 

STEP 106 

STICK 329 

STICK Function 329 

STOP 331 

STOP Statement 331 

STR$ 333 

converting from number to 
string 333 
STR$ Function 333 
STRIG 334 
STRIG Statement and 

Function 334 
STRIG(n) 336 
STRIG(n) Statement 336 
String formula too 

complex A- 15 
string space 32, 111 
String too long A- 1 5 
STRINGS 337 
STRINGS Function 337 
subroutines 118,203 
Subscript out of range A- 15 
subscripts 70, 233 
substring 152, 186, 300 
summary of changes v 
superimpose image 282 
SWAP 338 
SWAP Statement 338 
Syntax error A- 16 
SYSTEM 339 
SYSTEM Command 339 
system functions A- 15 
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u 



TAB 340 

TAB Function 340 

TAN 341 

TAN Function 341 

tangent 341 

tempo table 325 

terminating BASIC 339 

THEN 123 

tile painting 243 

tiling 237,238 

TIMES 342 

TIMES Variable and 

Statement 342 
time, duration 323 
TIMER 344 
TIMER Function 344 
tokenized format 309 
Too many files A- 16 
trace 345 
transfer image 282 
trapping, communications 46 
tree-structured directories 

changing 23 
triggers, joystick 334 
trigonometric functions 

arctangent 6 

cosine 50 
trigonometric sine 322 
trigonometric tangent 341 
TROFF 345 
TRON 345 
TRON and TROFF 

Commands 345 
true or false 310 
truncation 105, 138 
Type mismatch A- 16 



Undefined line number A- 16 
Undefined user function A- 17 
underflow A- 14 
underlined characters 40 
Unprintable error A- 17 
user workspace 32, 111 
user-defined functions 59 
USR 66, 346 
USR Function 346 



V 



VAL 352 

VAL Function 352 

VARPTR 353 

VARPTR Function 353 

VARPTR$ Function 355 

VIEW 357 

VIEW Statement 357, 370 

visual page 313 

vpage 313 



w 



WAIT 362 

WAIT Statement 362 

WEND 364 

WEND without WHILE A- 17 

WHILE 364 

WHILE and WEND 

Statements 364 
WHILE without WEND A- 17 
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WIDTH 366 Z 

WIDTH Statement 265,366 

WINDOW 357, 370 

WINDOW Statement 370 zones? print 2 63 

workspace 32, 111 zooming 373 

world coordinates 370 

WRITE 375 

WRITE # 377 

WRITE # Statement 377 

WRITE Statement 375 
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